1 @c Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999,
2 @c 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008
3 @c Free Software Foundation, Inc.
4 @c This is part of the GCC manual.
5 @c For copying conditions, see the file gcc.texi.
12 @c man begin COPYRIGHT
13 Copyright @copyright{} 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998,
14 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008
15 Free Software Foundation, Inc.
17 Permission is granted to copy, distribute and/or modify this document
18 under the terms of the GNU Free Documentation License, Version 1.2 or
19 any later version published by the Free Software Foundation; with the
20 Invariant Sections being ``GNU General Public License'' and ``Funding
21 Free Software'', the Front-Cover texts being (a) (see below), and with
22 the Back-Cover Texts being (b) (see below). A copy of the license is
23 included in the gfdl(7) man page.
25 (a) The FSF's Front-Cover Text is:
29 (b) The FSF's Back-Cover Text is:
31 You have freedom to copy and modify this GNU Manual, like GNU
32 software. Copies published by the Free Software Foundation raise
33 funds for GNU development.
35 @c Set file name and title for the man page.
37 @settitle GNU project C and C++ compiler
39 gcc [@option{-c}|@option{-S}|@option{-E}] [@option{-std=}@var{standard}]
40 [@option{-g}] [@option{-pg}] [@option{-O}@var{level}]
41 [@option{-W}@var{warn}@dots{}] [@option{-pedantic}]
42 [@option{-I}@var{dir}@dots{}] [@option{-L}@var{dir}@dots{}]
43 [@option{-D}@var{macro}[=@var{defn}]@dots{}] [@option{-U}@var{macro}]
44 [@option{-f}@var{option}@dots{}] [@option{-m}@var{machine-option}@dots{}]
45 [@option{-o} @var{outfile}] [@@@var{file}] @var{infile}@dots{}
47 Only the most useful options are listed here; see below for the
48 remainder. @samp{g++} accepts mostly the same options as @samp{gcc}.
51 gpl(7), gfdl(7), fsf-funding(7),
52 cpp(1), gcov(1), as(1), ld(1), gdb(1), adb(1), dbx(1), sdb(1)
53 and the Info entries for @file{gcc}, @file{cpp}, @file{as},
54 @file{ld}, @file{binutils} and @file{gdb}.
57 For instructions on reporting bugs, see
61 See the Info entry for @command{gcc}, or
62 @w{@uref{http://gcc.gnu.org/onlinedocs/gcc/Contributors.html}},
63 for contributors to GCC@.
68 @chapter GCC Command Options
69 @cindex GCC command options
70 @cindex command options
71 @cindex options, GCC command
73 @c man begin DESCRIPTION
74 When you invoke GCC, it normally does preprocessing, compilation,
75 assembly and linking. The ``overall options'' allow you to stop this
76 process at an intermediate stage. For example, the @option{-c} option
77 says not to run the linker. Then the output consists of object files
78 output by the assembler.
80 Other options are passed on to one stage of processing. Some options
81 control the preprocessor and others the compiler itself. Yet other
82 options control the assembler and linker; most of these are not
83 documented here, since you rarely need to use any of them.
85 @cindex C compilation options
86 Most of the command line options that you can use with GCC are useful
87 for C programs; when an option is only useful with another language
88 (usually C++), the explanation says so explicitly. If the description
89 for a particular option does not mention a source language, you can use
90 that option with all supported languages.
92 @cindex C++ compilation options
93 @xref{Invoking G++,,Compiling C++ Programs}, for a summary of special
94 options for compiling C++ programs.
96 @cindex grouping options
97 @cindex options, grouping
98 The @command{gcc} program accepts options and file names as operands. Many
99 options have multi-letter names; therefore multiple single-letter options
100 may @emph{not} be grouped: @option{-dr} is very different from @w{@samp{-d
103 @cindex order of options
104 @cindex options, order
105 You can mix options and other arguments. For the most part, the order
106 you use doesn't matter. Order does matter when you use several
107 options of the same kind; for example, if you specify @option{-L} more
108 than once, the directories are searched in the order specified. Also,
109 the placement of the @option{-l} option is significant.
111 Many options have long names starting with @samp{-f} or with
112 @samp{-W}---for example,
113 @option{-fmove-loop-invariants}, @option{-Wformat} and so on. Most of
114 these have both positive and negative forms; the negative form of
115 @option{-ffoo} would be @option{-fno-foo}. This manual documents
116 only one of these two forms, whichever one is not the default.
120 @xref{Option Index}, for an index to GCC's options.
123 * Option Summary:: Brief list of all options, without explanations.
124 * Overall Options:: Controlling the kind of output:
125 an executable, object files, assembler files,
126 or preprocessed source.
127 * Invoking G++:: Compiling C++ programs.
128 * C Dialect Options:: Controlling the variant of C language compiled.
129 * C++ Dialect Options:: Variations on C++.
130 * Objective-C and Objective-C++ Dialect Options:: Variations on Objective-C
132 * Language Independent Options:: Controlling how diagnostics should be
134 * Warning Options:: How picky should the compiler be?
135 * Debugging Options:: Symbol tables, measurements, and debugging dumps.
136 * Optimize Options:: How much optimization?
137 * Preprocessor Options:: Controlling header files and macro definitions.
138 Also, getting dependency information for Make.
139 * Assembler Options:: Passing options to the assembler.
140 * Link Options:: Specifying libraries and so on.
141 * Directory Options:: Where to find header files and libraries.
142 Where to find the compiler executable files.
143 * Spec Files:: How to pass switches to sub-processes.
144 * Target Options:: Running a cross-compiler, or an old version of GCC.
145 * Submodel Options:: Specifying minor hardware or convention variations,
146 such as 68010 vs 68020.
147 * Code Gen Options:: Specifying conventions for function calls, data layout
149 * Environment Variables:: Env vars that affect GCC.
150 * Precompiled Headers:: Compiling a header once, and using it many times.
151 * Running Protoize:: Automatically adding or removing function prototypes.
157 @section Option Summary
159 Here is a summary of all the options, grouped by type. Explanations are
160 in the following sections.
163 @item Overall Options
164 @xref{Overall Options,,Options Controlling the Kind of Output}.
165 @gccoptlist{-c -S -E -o @var{file} -combine -pipe -pass-exit-codes @gol
166 -x @var{language} -v -### --help@r{[}=@var{class}@r{]} --target-help @gol
167 --version @@@var{file}}
169 @item C Language Options
170 @xref{C Dialect Options,,Options Controlling C Dialect}.
171 @gccoptlist{-ansi -std=@var{standard} -fgnu89-inline @gol
172 -aux-info @var{filename} @gol
173 -fno-asm -fno-builtin -fno-builtin-@var{function} @gol
174 -fhosted -ffreestanding -fopenmp -fms-extensions @gol
175 -trigraphs -no-integrated-cpp -traditional -traditional-cpp @gol
176 -fallow-single-precision -fcond-mismatch -flax-vector-conversions @gol
177 -fsigned-bitfields -fsigned-char @gol
178 -funsigned-bitfields -funsigned-char}
180 @item C++ Language Options
181 @xref{C++ Dialect Options,,Options Controlling C++ Dialect}.
182 @gccoptlist{-fabi-version=@var{n} -fno-access-control -fcheck-new @gol
183 -fconserve-space -ffriend-injection @gol
184 -fno-elide-constructors @gol
185 -fno-enforce-eh-specs @gol
186 -ffor-scope -fno-for-scope -fno-gnu-keywords @gol
187 -fno-implicit-templates @gol
188 -fno-implicit-inline-templates @gol
189 -fno-implement-inlines -fms-extensions @gol
190 -fno-nonansi-builtins -fno-operator-names @gol
191 -fno-optional-diags -fpermissive @gol
192 -frepo -fno-rtti -fstats -ftemplate-depth-@var{n} @gol
193 -fno-threadsafe-statics -fuse-cxa-atexit -fno-weak -nostdinc++ @gol
194 -fno-default-inline -fvisibility-inlines-hidden @gol
195 -fvisibility-ms-compat @gol
196 -Wabi -Wctor-dtor-privacy @gol
197 -Wnon-virtual-dtor -Wreorder @gol
198 -Weffc++ -Wno-deprecated -Wstrict-null-sentinel @gol
199 -Wno-non-template-friend -Wold-style-cast @gol
200 -Woverloaded-virtual -Wno-pmf-conversions @gol
203 @item Objective-C and Objective-C++ Language Options
204 @xref{Objective-C and Objective-C++ Dialect Options,,Options Controlling
205 Objective-C and Objective-C++ Dialects}.
206 @gccoptlist{-fconstant-string-class=@var{class-name} @gol
207 -fgnu-runtime -fnext-runtime @gol
208 -fno-nil-receivers @gol
209 -fobjc-call-cxx-cdtors @gol
210 -fobjc-direct-dispatch @gol
211 -fobjc-exceptions @gol
213 -freplace-objc-classes @gol
216 -Wassign-intercept @gol
217 -Wno-protocol -Wselector @gol
218 -Wstrict-selector-match @gol
219 -Wundeclared-selector}
221 @item Language Independent Options
222 @xref{Language Independent Options,,Options to Control Diagnostic Messages Formatting}.
223 @gccoptlist{-fmessage-length=@var{n} @gol
224 -fdiagnostics-show-location=@r{[}once@r{|}every-line@r{]} @gol
225 -fdiagnostics-show-option}
227 @item Warning Options
228 @xref{Warning Options,,Options to Request or Suppress Warnings}.
229 @gccoptlist{-fsyntax-only -pedantic -pedantic-errors @gol
230 -w -Wextra -Wall -Waddress -Waggregate-return -Warray-bounds @gol
231 -Wno-attributes -Wc++-compat -Wc++0x-compat -Wcast-align -Wcast-qual @gol
232 -Wchar-subscripts -Wclobbered -Wcomment @gol
233 -Wconversion -Wcoverage-mismatch -Wno-deprecated-declarations @gol
234 -Wdisabled-optimization -Wno-div-by-zero @gol
235 -Wempty-body -Wno-endif-labels @gol
236 -Werror -Werror=* @gol
237 -Wfatal-errors -Wfloat-equal -Wformat -Wformat=2 @gol
238 -Wno-format-contains-nul -Wno-format-extra-args -Wformat-nonliteral @gol
239 -Wformat-security -Wformat-y2k @gol
240 -Wframe-larger-than=@var{len} -Wignored-qualifiers @gol
241 -Wimplicit -Wimplicit-function-declaration -Wimplicit-int @gol
242 -Wimport -Wno-import -Winit-self -Winline @gol
243 -Wno-int-to-pointer-cast -Wno-invalid-offsetof @gol
244 -Winvalid-pch -Wlarger-than=@var{len} -Wunsafe-loop-optimizations @gol
245 -Wlogical-op -Wlong-long @gol
246 -Wmain -Wmissing-braces -Wmissing-field-initializers @gol
247 -Wmissing-format-attribute -Wmissing-include-dirs @gol
248 -Wmissing-noreturn @gol
249 -Wno-multichar -Wnonnull -Wno-overflow @gol
250 -Woverlength-strings -Wpacked -Wpadded @gol
251 -Wparentheses -Wpointer-arith -Wno-pointer-to-int-cast @gol
252 -Wredundant-decls @gol
253 -Wreturn-type -Wsequence-point -Wshadow @gol
254 -Wsign-compare -Wsign-conversion -Wstack-protector @gol
255 -Wstrict-aliasing -Wstrict-aliasing=n @gol
256 -Wstrict-overflow -Wstrict-overflow=@var{n} @gol
257 -Wswitch -Wswitch-default -Wswitch-enum @gol
258 -Wsystem-headers -Wtrigraphs -Wtype-limits -Wundef -Wuninitialized @gol
259 -Wunknown-pragmas -Wno-pragmas -Wunreachable-code @gol
260 -Wunused -Wunused-function -Wunused-label -Wunused-parameter @gol
261 -Wunused-value -Wunused-variable @gol
262 -Wvariadic-macros -Wvla @gol
263 -Wvolatile-register-var -Wwrite-strings}
265 @item C and Objective-C-only Warning Options
266 @gccoptlist{-Wbad-function-cast -Wmissing-declarations @gol
267 -Wmissing-parameter-type -Wmissing-prototypes -Wnested-externs @gol
268 -Wold-style-declaration -Wold-style-definition @gol
269 -Wstrict-prototypes -Wtraditional -Wtraditional-conversion @gol
270 -Wdeclaration-after-statement -Wpointer-sign}
272 @item Debugging Options
273 @xref{Debugging Options,,Options for Debugging Your Program or GCC}.
274 @gccoptlist{-d@var{letters} -dumpspecs -dumpmachine -dumpversion @gol
275 -fdbg-cnt-list -fdbg-cnt=@var{counter-value-list} @gol
276 -fdump-noaddr -fdump-unnumbered -fdump-translation-unit@r{[}-@var{n}@r{]} @gol
277 -fdump-class-hierarchy@r{[}-@var{n}@r{]} @gol
278 -fdump-ipa-all -fdump-ipa-cgraph -fdump-ipa-inline @gol
280 -fdump-tree-original@r{[}-@var{n}@r{]} @gol
281 -fdump-tree-optimized@r{[}-@var{n}@r{]} @gol
282 -fdump-tree-cfg -fdump-tree-vcg -fdump-tree-alias @gol
284 -fdump-tree-ssa@r{[}-@var{n}@r{]} -fdump-tree-pre@r{[}-@var{n}@r{]} @gol
285 -fdump-tree-ccp@r{[}-@var{n}@r{]} -fdump-tree-dce@r{[}-@var{n}@r{]} @gol
286 -fdump-tree-gimple@r{[}-raw@r{]} -fdump-tree-mudflap@r{[}-@var{n}@r{]} @gol
287 -fdump-tree-dom@r{[}-@var{n}@r{]} @gol
288 -fdump-tree-dse@r{[}-@var{n}@r{]} @gol
289 -fdump-tree-phiopt@r{[}-@var{n}@r{]} @gol
290 -fdump-tree-forwprop@r{[}-@var{n}@r{]} @gol
291 -fdump-tree-copyrename@r{[}-@var{n}@r{]} @gol
292 -fdump-tree-nrv -fdump-tree-vect @gol
293 -fdump-tree-sink @gol
294 -fdump-tree-sra@r{[}-@var{n}@r{]} @gol
295 -fdump-tree-salias @gol
296 -fdump-tree-fre@r{[}-@var{n}@r{]} @gol
297 -fdump-tree-vrp@r{[}-@var{n}@r{]} @gol
298 -ftree-vectorizer-verbose=@var{n} @gol
299 -fdump-tree-storeccp@r{[}-@var{n}@r{]} @gol
300 -feliminate-dwarf2-dups -feliminate-unused-debug-types @gol
301 -feliminate-unused-debug-symbols -femit-class-debug-always @gol
302 -fmem-report -fpre-ipa-mem-report -fpost-ipa-mem-report -fprofile-arcs @gol
303 -frandom-seed=@var{string} -fsched-verbose=@var{n} @gol
304 -ftest-coverage -ftime-report -fvar-tracking @gol
305 -g -g@var{level} -gcoff -gdwarf-2 @gol
306 -ggdb -gstabs -gstabs+ -gvms -gxcoff -gxcoff+ @gol
307 -fno-merge-debug-strings -fdebug-prefix-map=@var{old}=@var{new} @gol
308 -femit-struct-debug-baseonly -femit-struct-debug-reduced @gol
309 -femit-struct-debug-detailed@r{[}=@var{spec-list}@r{]} @gol
310 -p -pg -print-file-name=@var{library} -print-libgcc-file-name @gol
311 -print-multi-directory -print-multi-lib @gol
312 -print-prog-name=@var{program} -print-search-dirs -Q @gol
313 -print-sysroot-headers-suffix @gol
316 @item Optimization Options
317 @xref{Optimize Options,,Options that Control Optimization}.
319 -falign-functions[=@var{n}] -falign-jumps[=@var{n}] @gol
320 -falign-labels[=@var{n}] -falign-loops[=@var{n}] -fassociative-math @gol
321 -fauto-inc-dec -fbranch-probabilities -fbranch-target-load-optimize @gol
322 -fbranch-target-load-optimize2 -fbtr-bb-exclusive -fcaller-saves @gol
323 -fcheck-data-deps -fcprop-registers -fcrossjumping -fcse-follow-jumps @gol
324 -fcse-skip-blocks -fcx-fortran-rules -fcx-limited-range @gol
325 -fdata-sections -fdce -fdce @gol
326 -fdelayed-branch -fdelete-null-pointer-checks -fdse -fdse @gol
327 -fearly-inlining -fexpensive-optimizations -ffast-math @gol
328 -ffinite-math-only -ffloat-store -fforward-propagate @gol
329 -ffunction-sections -fgcse -fgcse-after-reload -fgcse-las -fgcse-lm @gol
330 -fgcse-sm -fif-conversion -fif-conversion2 -finline-functions @gol
331 -finline-functions-called-once -finline-limit=@var{n} @gol
332 -finline-small-functions -fipa-cp -fipa-marix-reorg -fipa-pta @gol
333 -fipa-pure-const -fipa-reference -fipa-struct-reorg @gol
334 -fipa-type-escape -fivopts -fkeep-inline-functions -fkeep-static-consts @gol
335 -fmerge-all-constants -fmerge-constants -fmodulo-sched @gol
336 -fmodulo-sched-allow-regmoves -fmove-loop-invariants -fmudflap @gol
337 -fmudflapir -fmudflapth -fno-branch-count-reg -fno-default-inline @gol
338 -fno-defer-pop -fno-function-cse -fno-guess-branch-probability @gol
339 -fno-inline -fno-math-errno -fno-peephole -fno-peephole2 @gol
340 -fno-sched-interblock -fno-sched-spec -fno-signed-zeros @gol
341 -fno-toplevel-reorder -fno-trapping-math -fno-zero-initialized-in-bss @gol
342 -fomit-frame-pointer -foptimize-register-move -foptimize-sibling-calls @gol
343 -fpeel-loops -fpredictive-commoning -fprefetch-loop-arrays @gol
344 -fprofile-generate -fprofile-use -fprofile-values -freciprocal-math @gol
345 -fregmove -frename-registers -freorder-blocks @gol
346 -freorder-blocks-and-partition -freorder-functions @gol
347 -frerun-cse-after-loop -freschedule-modulo-scheduled-loops @gol
348 -frounding-math -frtl-abstract-sequences -fsched2-use-superblocks @gol
349 -fsched2-use-traces -fsched-spec-load -fsched-spec-load-dangerous @gol
350 -fsched-stalled-insns-dep[=@var{n}] -fsched-stalled-insns[=@var{n}] @gol
351 -fschedule-insns -fschedule-insns2 -fsection-anchors -fsee @gol
352 -fsignaling-nans -fsingle-precision-constant -fsplit-ivs-in-unroller @gol
353 -fsplit-wide-types -fstack-protector -fstack-protector-all @gol
354 -fstrict-aliasing -fstrict-overflow -fthread-jumps -ftracer -ftree-ccp @gol
355 -ftree-ch -ftree-copy-prop -ftree-copyrename -ftree-dce @gol
356 -ftree-dominator-opts -ftree-dse -ftree-fre -ftree-loop-im @gol
357 -ftree-loop-distribution @gol
358 -ftree-loop-ivcanon -ftree-loop-linear -ftree-loop-optimize @gol
359 -ftree-parallelize-loops=@var{n} -ftree-pre -ftree-reassoc -ftree-salias @gol
360 -ftree-sink -ftree-sra -ftree-store-ccp -ftree-ter @gol
361 -ftree-vect-loop-version -ftree-vectorize -ftree-vrp -funit-at-a-time @gol
362 -funroll-all-loops -funroll-loops -funsafe-loop-optimizations @gol
363 -funsafe-math-optimizations -funswitch-loops @gol
364 -fvariable-expansion-in-unroller -fvect-cost-model -fvpt -fweb @gol
366 --param @var{name}=@var{value}
367 -O -O0 -O1 -O2 -O3 -Os}
369 @item Preprocessor Options
370 @xref{Preprocessor Options,,Options Controlling the Preprocessor}.
371 @gccoptlist{-A@var{question}=@var{answer} @gol
372 -A-@var{question}@r{[}=@var{answer}@r{]} @gol
373 -C -dD -dI -dM -dN @gol
374 -D@var{macro}@r{[}=@var{defn}@r{]} -E -H @gol
375 -idirafter @var{dir} @gol
376 -include @var{file} -imacros @var{file} @gol
377 -iprefix @var{file} -iwithprefix @var{dir} @gol
378 -iwithprefixbefore @var{dir} -isystem @var{dir} @gol
379 -imultilib @var{dir} -isysroot @var{dir} @gol
380 -M -MM -MF -MG -MP -MQ -MT -nostdinc @gol
381 -P -fworking-directory -remap @gol
382 -trigraphs -undef -U@var{macro} -Wp,@var{option} @gol
383 -Xpreprocessor @var{option}}
385 @item Assembler Option
386 @xref{Assembler Options,,Passing Options to the Assembler}.
387 @gccoptlist{-Wa,@var{option} -Xassembler @var{option}}
390 @xref{Link Options,,Options for Linking}.
391 @gccoptlist{@var{object-file-name} -l@var{library} @gol
392 -nostartfiles -nodefaultlibs -nostdlib -pie -rdynamic @gol
393 -s -static -static-libgcc -shared -shared-libgcc -symbolic @gol
394 -Wl,@var{option} -Xlinker @var{option} @gol
397 @item Directory Options
398 @xref{Directory Options,,Options for Directory Search}.
399 @gccoptlist{-B@var{prefix} -I@var{dir} -iquote@var{dir} -L@var{dir}
400 -specs=@var{file} -I- --sysroot=@var{dir}}
403 @c I wrote this xref this way to avoid overfull hbox. -- rms
404 @xref{Target Options}.
405 @gccoptlist{-V @var{version} -b @var{machine}}
407 @item Machine Dependent Options
408 @xref{Submodel Options,,Hardware Models and Configurations}.
409 @c This list is ordered alphanumerically by subsection name.
410 @c Try and put the significant identifier (CPU or system) first,
411 @c so users have a clue at guessing where the ones they want will be.
414 @gccoptlist{-EB -EL @gol
415 -mmangle-cpu -mcpu=@var{cpu} -mtext=@var{text-section} @gol
416 -mdata=@var{data-section} -mrodata=@var{readonly-data-section}}
419 @gccoptlist{-mapcs-frame -mno-apcs-frame @gol
420 -mabi=@var{name} @gol
421 -mapcs-stack-check -mno-apcs-stack-check @gol
422 -mapcs-float -mno-apcs-float @gol
423 -mapcs-reentrant -mno-apcs-reentrant @gol
424 -msched-prolog -mno-sched-prolog @gol
425 -mlittle-endian -mbig-endian -mwords-little-endian @gol
426 -mfloat-abi=@var{name} -msoft-float -mhard-float -mfpe @gol
427 -mthumb-interwork -mno-thumb-interwork @gol
428 -mcpu=@var{name} -march=@var{name} -mfpu=@var{name} @gol
429 -mstructure-size-boundary=@var{n} @gol
430 -mabort-on-noreturn @gol
431 -mlong-calls -mno-long-calls @gol
432 -msingle-pic-base -mno-single-pic-base @gol
433 -mpic-register=@var{reg} @gol
434 -mnop-fun-dllimport @gol
435 -mcirrus-fix-invalid-insns -mno-cirrus-fix-invalid-insns @gol
436 -mpoke-function-name @gol
438 -mtpcs-frame -mtpcs-leaf-frame @gol
439 -mcaller-super-interworking -mcallee-super-interworking @gol
443 @gccoptlist{-mmcu=@var{mcu} -msize -minit-stack=@var{n} -mno-interrupts @gol
444 -mcall-prologues -mno-tablejump -mtiny-stack -mint8}
446 @emph{Blackfin Options}
447 @gccoptlist{-mcpu=@var{cpu}@r{[}-@var{sirevision}@r{]} @gol
448 -msim -momit-leaf-frame-pointer -mno-omit-leaf-frame-pointer @gol
449 -mspecld-anomaly -mno-specld-anomaly -mcsync-anomaly -mno-csync-anomaly @gol
450 -mlow-64k -mno-low64k -mstack-check-l1 -mid-shared-library @gol
451 -mno-id-shared-library -mshared-library-id=@var{n} @gol
452 -mleaf-id-shared-library -mno-leaf-id-shared-library @gol
453 -msep-data -mno-sep-data -mlong-calls -mno-long-calls @gol
454 -mfast-fp -minline-plt}
457 @gccoptlist{-mcpu=@var{cpu} -march=@var{cpu} -mtune=@var{cpu} @gol
458 -mmax-stack-frame=@var{n} -melinux-stacksize=@var{n} @gol
459 -metrax4 -metrax100 -mpdebug -mcc-init -mno-side-effects @gol
460 -mstack-align -mdata-align -mconst-align @gol
461 -m32-bit -m16-bit -m8-bit -mno-prologue-epilogue -mno-gotplt @gol
462 -melf -maout -melinux -mlinux -sim -sim2 @gol
463 -mmul-bug-workaround -mno-mul-bug-workaround}
466 @gccoptlist{-mmac -mpush-args}
468 @emph{Darwin Options}
469 @gccoptlist{-all_load -allowable_client -arch -arch_errors_fatal @gol
470 -arch_only -bind_at_load -bundle -bundle_loader @gol
471 -client_name -compatibility_version -current_version @gol
473 -dependency-file -dylib_file -dylinker_install_name @gol
474 -dynamic -dynamiclib -exported_symbols_list @gol
475 -filelist -flat_namespace -force_cpusubtype_ALL @gol
476 -force_flat_namespace -headerpad_max_install_names @gol
478 -image_base -init -install_name -keep_private_externs @gol
479 -multi_module -multiply_defined -multiply_defined_unused @gol
480 -noall_load -no_dead_strip_inits_and_terms @gol
481 -nofixprebinding -nomultidefs -noprebind -noseglinkedit @gol
482 -pagezero_size -prebind -prebind_all_twolevel_modules @gol
483 -private_bundle -read_only_relocs -sectalign @gol
484 -sectobjectsymbols -whyload -seg1addr @gol
485 -sectcreate -sectobjectsymbols -sectorder @gol
486 -segaddr -segs_read_only_addr -segs_read_write_addr @gol
487 -seg_addr_table -seg_addr_table_filename -seglinkedit @gol
488 -segprot -segs_read_only_addr -segs_read_write_addr @gol
489 -single_module -static -sub_library -sub_umbrella @gol
490 -twolevel_namespace -umbrella -undefined @gol
491 -unexported_symbols_list -weak_reference_mismatches @gol
492 -whatsloaded -F -gused -gfull -mmacosx-version-min=@var{version} @gol
493 -mkernel -mone-byte-bool}
495 @emph{DEC Alpha Options}
496 @gccoptlist{-mno-fp-regs -msoft-float -malpha-as -mgas @gol
497 -mieee -mieee-with-inexact -mieee-conformant @gol
498 -mfp-trap-mode=@var{mode} -mfp-rounding-mode=@var{mode} @gol
499 -mtrap-precision=@var{mode} -mbuild-constants @gol
500 -mcpu=@var{cpu-type} -mtune=@var{cpu-type} @gol
501 -mbwx -mmax -mfix -mcix @gol
502 -mfloat-vax -mfloat-ieee @gol
503 -mexplicit-relocs -msmall-data -mlarge-data @gol
504 -msmall-text -mlarge-text @gol
505 -mmemory-latency=@var{time}}
507 @emph{DEC Alpha/VMS Options}
508 @gccoptlist{-mvms-return-codes}
511 @gccoptlist{-mgpr-32 -mgpr-64 -mfpr-32 -mfpr-64 @gol
512 -mhard-float -msoft-float @gol
513 -malloc-cc -mfixed-cc -mdword -mno-dword @gol
514 -mdouble -mno-double @gol
515 -mmedia -mno-media -mmuladd -mno-muladd @gol
516 -mfdpic -minline-plt -mgprel-ro -multilib-library-pic @gol
517 -mlinked-fp -mlong-calls -malign-labels @gol
518 -mlibrary-pic -macc-4 -macc-8 @gol
519 -mpack -mno-pack -mno-eflags -mcond-move -mno-cond-move @gol
520 -moptimize-membar -mno-optimize-membar @gol
521 -mscc -mno-scc -mcond-exec -mno-cond-exec @gol
522 -mvliw-branch -mno-vliw-branch @gol
523 -mmulti-cond-exec -mno-multi-cond-exec -mnested-cond-exec @gol
524 -mno-nested-cond-exec -mtomcat-stats @gol
528 @emph{GNU/Linux Options}
529 @gccoptlist{-muclibc}
531 @emph{H8/300 Options}
532 @gccoptlist{-mrelax -mh -ms -mn -mint32 -malign-300}
535 @gccoptlist{-march=@var{architecture-type} @gol
536 -mbig-switch -mdisable-fpregs -mdisable-indexing @gol
537 -mfast-indirect-calls -mgas -mgnu-ld -mhp-ld @gol
538 -mfixed-range=@var{register-range} @gol
539 -mjump-in-delay -mlinker-opt -mlong-calls @gol
540 -mlong-load-store -mno-big-switch -mno-disable-fpregs @gol
541 -mno-disable-indexing -mno-fast-indirect-calls -mno-gas @gol
542 -mno-jump-in-delay -mno-long-load-store @gol
543 -mno-portable-runtime -mno-soft-float @gol
544 -mno-space-regs -msoft-float -mpa-risc-1-0 @gol
545 -mpa-risc-1-1 -mpa-risc-2-0 -mportable-runtime @gol
546 -mschedule=@var{cpu-type} -mspace-regs -msio -mwsio @gol
547 -munix=@var{unix-std} -nolibdld -static -threads}
549 @emph{i386 and x86-64 Options}
550 @gccoptlist{-mtune=@var{cpu-type} -march=@var{cpu-type} @gol
551 -mfpmath=@var{unit} @gol
552 -masm=@var{dialect} -mno-fancy-math-387 @gol
553 -mno-fp-ret-in-387 -msoft-float @gol
554 -mno-wide-multiply -mrtd -malign-double @gol
555 -mpreferred-stack-boundary=@var{num} -mcx16 -msahf -mrecip @gol
556 -mmmx -msse -msse2 -msse3 -mssse3 -msse4.1 -msse4.2 -msse4 @gol
557 -msse4a -m3dnow -mpopcnt -mabm -msse5 @gol
558 -mthreads -mno-align-stringops -minline-all-stringops @gol
559 -mpush-args -maccumulate-outgoing-args -m128bit-long-double @gol
560 -m96bit-long-double -mregparm=@var{num} -msseregparm @gol
561 -mveclibabi=@var{type} -mpc32 -mpc64 -mpc80 -mstackrealign @gol
562 -momit-leaf-frame-pointer -mno-red-zone -mno-tls-direct-seg-refs @gol
563 -mcmodel=@var{code-model} @gol
564 -m32 -m64 -mlarge-data-threshold=@var{num} @gol
565 -mfused-madd -mno-fused-madd}
568 @gccoptlist{-mbig-endian -mlittle-endian -mgnu-as -mgnu-ld -mno-pic @gol
569 -mvolatile-asm-stop -mregister-names -mno-sdata @gol
570 -mconstant-gp -mauto-pic -minline-float-divide-min-latency @gol
571 -minline-float-divide-max-throughput @gol
572 -minline-int-divide-min-latency @gol
573 -minline-int-divide-max-throughput @gol
574 -minline-sqrt-min-latency -minline-sqrt-max-throughput @gol
575 -mno-dwarf2-asm -mearly-stop-bits @gol
576 -mfixed-range=@var{register-range} -mtls-size=@var{tls-size} @gol
577 -mtune=@var{cpu-type} -mt -pthread -milp32 -mlp64 @gol
578 -mno-sched-br-data-spec -msched-ar-data-spec -mno-sched-control-spec @gol
579 -msched-br-in-data-spec -msched-ar-in-data-spec -msched-in-control-spec @gol
580 -msched-ldc -mno-sched-control-ldc -mno-sched-spec-verbose @gol
581 -mno-sched-prefer-non-data-spec-insns @gol
582 -mno-sched-prefer-non-control-spec-insns @gol
583 -mno-sched-count-spec-in-critical-path}
585 @emph{M32R/D Options}
586 @gccoptlist{-m32r2 -m32rx -m32r @gol
588 -malign-loops -mno-align-loops @gol
589 -missue-rate=@var{number} @gol
590 -mbranch-cost=@var{number} @gol
591 -mmodel=@var{code-size-model-type} @gol
592 -msdata=@var{sdata-type} @gol
593 -mno-flush-func -mflush-func=@var{name} @gol
594 -mno-flush-trap -mflush-trap=@var{number} @gol
598 @gccoptlist{-mcpu=@var{cpu} -msim -memregs=@var{number}}
600 @emph{M680x0 Options}
601 @gccoptlist{-march=@var{arch} -mcpu=@var{cpu} -mtune=@var{tune}
602 -m68000 -m68020 -m68020-40 -m68020-60 -m68030 -m68040 @gol
603 -m68060 -mcpu32 -m5200 -m5206e -m528x -m5307 -m5407 @gol
604 -mcfv4e -mbitfield -mno-bitfield -mc68000 -mc68020 @gol
605 -mnobitfield -mrtd -mno-rtd -mdiv -mno-div -mshort @gol
606 -mno-short -mhard-float -m68881 -msoft-float -mpcrel @gol
607 -malign-int -mstrict-align -msep-data -mno-sep-data @gol
608 -mshared-library-id=n -mid-shared-library -mno-id-shared-library}
610 @emph{M68hc1x Options}
611 @gccoptlist{-m6811 -m6812 -m68hc11 -m68hc12 -m68hcs12 @gol
612 -mauto-incdec -minmax -mlong-calls -mshort @gol
613 -msoft-reg-count=@var{count}}
616 @gccoptlist{-mhardlit -mno-hardlit -mdiv -mno-div -mrelax-immediates @gol
617 -mno-relax-immediates -mwide-bitfields -mno-wide-bitfields @gol
618 -m4byte-functions -mno-4byte-functions -mcallgraph-data @gol
619 -mno-callgraph-data -mslow-bytes -mno-slow-bytes -mno-lsim @gol
620 -mlittle-endian -mbig-endian -m210 -m340 -mstack-increment}
623 @gccoptlist{-EL -EB -march=@var{arch} -mtune=@var{arch} @gol
624 -mips1 -mips2 -mips3 -mips4 -mips32 -mips32r2 -mips64 @gol
625 -mips16 -mno-mips16 -mflip-mips16 @gol
626 -minterlink-mips16 -mno-interlink-mips16 @gol
627 -mabi=@var{abi} -mabicalls -mno-abicalls @gol
628 -mshared -mno-shared -mxgot -mno-xgot -mgp32 -mgp64 @gol
629 -mfp32 -mfp64 -mhard-float -msoft-float @gol
630 -msingle-float -mdouble-float -mdsp -mno-dsp -mdspr2 -mno-dspr2 @gol
631 -msmartmips -mno-smartmips @gol
632 -mpaired-single -mno-paired-single -mdmx -mno-mdmx @gol
633 -mips3d -mno-mips3d -mmt -mno-mt -mllsc -mno-llsc @gol
634 -mlong64 -mlong32 -msym32 -mno-sym32 @gol
635 -G@var{num} -mlocal-sdata -mno-local-sdata @gol
636 -mextern-sdata -mno-extern-sdata -mgpopt -mno-gopt @gol
637 -membedded-data -mno-embedded-data @gol
638 -muninit-const-in-rodata -mno-uninit-const-in-rodata @gol
639 -mcode-readable=@var{setting} @gol
640 -msplit-addresses -mno-split-addresses @gol
641 -mexplicit-relocs -mno-explicit-relocs @gol
642 -mcheck-zero-division -mno-check-zero-division @gol
643 -mdivide-traps -mdivide-breaks @gol
644 -mmemcpy -mno-memcpy -mlong-calls -mno-long-calls @gol
645 -mmad -mno-mad -mfused-madd -mno-fused-madd -nocpp @gol
646 -mfix-r4000 -mno-fix-r4000 -mfix-r4400 -mno-fix-r4400 @gol
647 -mfix-vr4120 -mno-fix-vr4120 -mfix-vr4130 -mno-fix-vr4130 @gol
648 -mfix-sb1 -mno-fix-sb1 @gol
649 -mflush-func=@var{func} -mno-flush-func @gol
650 -mbranch-cost=@var{num} -mbranch-likely -mno-branch-likely @gol
651 -mfp-exceptions -mno-fp-exceptions @gol
652 -mvr4130-align -mno-vr4130-align}
655 @gccoptlist{-mlibfuncs -mno-libfuncs -mepsilon -mno-epsilon -mabi=gnu @gol
656 -mabi=mmixware -mzero-extend -mknuthdiv -mtoplevel-symbols @gol
657 -melf -mbranch-predict -mno-branch-predict -mbase-addresses @gol
658 -mno-base-addresses -msingle-exit -mno-single-exit}
660 @emph{MN10300 Options}
661 @gccoptlist{-mmult-bug -mno-mult-bug @gol
662 -mam33 -mno-am33 @gol
663 -mam33-2 -mno-am33-2 @gol
664 -mreturn-pointer-on-d0 @gol
668 @gccoptlist{-mno-crt0 -mbacc -msim @gol
669 -march=@var{cpu-type} }
671 @emph{PDP-11 Options}
672 @gccoptlist{-mfpu -msoft-float -mac0 -mno-ac0 -m40 -m45 -m10 @gol
673 -mbcopy -mbcopy-builtin -mint32 -mno-int16 @gol
674 -mint16 -mno-int32 -mfloat32 -mno-float64 @gol
675 -mfloat64 -mno-float32 -mabshi -mno-abshi @gol
676 -mbranch-expensive -mbranch-cheap @gol
677 -msplit -mno-split -munix-asm -mdec-asm}
679 @emph{PowerPC Options}
680 See RS/6000 and PowerPC Options.
682 @emph{RS/6000 and PowerPC Options}
683 @gccoptlist{-mcpu=@var{cpu-type} @gol
684 -mtune=@var{cpu-type} @gol
685 -mpower -mno-power -mpower2 -mno-power2 @gol
686 -mpowerpc -mpowerpc64 -mno-powerpc @gol
687 -maltivec -mno-altivec @gol
688 -mpowerpc-gpopt -mno-powerpc-gpopt @gol
689 -mpowerpc-gfxopt -mno-powerpc-gfxopt @gol
690 -mmfcrf -mno-mfcrf -mpopcntb -mno-popcntb -mfprnd -mno-fprnd @gol
691 -mcmpb -mno-cmpb -mmfpgpr -mno-mfpgpr -mhard-dfp -mno-hard-dfp @gol
692 -mnew-mnemonics -mold-mnemonics @gol
693 -mfull-toc -mminimal-toc -mno-fp-in-toc -mno-sum-in-toc @gol
694 -m64 -m32 -mxl-compat -mno-xl-compat -mpe @gol
695 -malign-power -malign-natural @gol
696 -msoft-float -mhard-float -mmultiple -mno-multiple @gol
697 -mstring -mno-string -mupdate -mno-update @gol
698 -mfused-madd -mno-fused-madd -mbit-align -mno-bit-align @gol
699 -mstrict-align -mno-strict-align -mrelocatable @gol
700 -mno-relocatable -mrelocatable-lib -mno-relocatable-lib @gol
701 -mtoc -mno-toc -mlittle -mlittle-endian -mbig -mbig-endian @gol
702 -mdynamic-no-pic -maltivec -mswdiv @gol
703 -mprioritize-restricted-insns=@var{priority} @gol
704 -msched-costly-dep=@var{dependence_type} @gol
705 -minsert-sched-nops=@var{scheme} @gol
706 -mcall-sysv -mcall-netbsd @gol
707 -maix-struct-return -msvr4-struct-return @gol
708 -mabi=@var{abi-type} -msecure-plt -mbss-plt @gol
709 -misel -mno-isel @gol
710 -misel=yes -misel=no @gol
712 -mspe=yes -mspe=no @gol
714 -mvrsave -mno-vrsave @gol
715 -mmulhw -mno-mulhw @gol
716 -mdlmzb -mno-dlmzb @gol
717 -mfloat-gprs=yes -mfloat-gprs=no -mfloat-gprs=single -mfloat-gprs=double @gol
718 -mprototype -mno-prototype @gol
719 -msim -mmvme -mads -myellowknife -memb -msdata @gol
720 -msdata=@var{opt} -mvxworks -mwindiss -G @var{num} -pthread}
722 @emph{S/390 and zSeries Options}
723 @gccoptlist{-mtune=@var{cpu-type} -march=@var{cpu-type} @gol
724 -mhard-float -msoft-float -mlong-double-64 -mlong-double-128 @gol
725 -mbackchain -mno-backchain -mpacked-stack -mno-packed-stack @gol
726 -msmall-exec -mno-small-exec -mmvcle -mno-mvcle @gol
727 -m64 -m31 -mdebug -mno-debug -mesa -mzarch @gol
728 -mtpf-trace -mno-tpf-trace -mfused-madd -mno-fused-madd @gol
729 -mwarn-framesize -mwarn-dynamicstack -mstack-size -mstack-guard}
732 @gccoptlist{-meb -mel @gol
736 -mscore5 -mscore5u -mscore7 -mscore7d}
739 @gccoptlist{-m1 -m2 -m2e -m3 -m3e @gol
740 -m4-nofpu -m4-single-only -m4-single -m4 @gol
741 -m4a-nofpu -m4a-single-only -m4a-single -m4a -m4al @gol
742 -m5-64media -m5-64media-nofpu @gol
743 -m5-32media -m5-32media-nofpu @gol
744 -m5-compact -m5-compact-nofpu @gol
745 -mb -ml -mdalign -mrelax @gol
746 -mbigtable -mfmovd -mhitachi -mrenesas -mno-renesas -mnomacsave @gol
747 -mieee -misize -minline-ic_invalidate -mpadstruct -mspace @gol
748 -mprefergot -musermode -multcost=@var{number} -mdiv=@var{strategy} @gol
749 -mdivsi3_libfunc=@var{name} @gol
750 -madjust-unroll -mindexed-addressing -mgettrcost=@var{number} -mpt-fixed @gol
754 @gccoptlist{-mcpu=@var{cpu-type} @gol
755 -mtune=@var{cpu-type} @gol
756 -mcmodel=@var{code-model} @gol
757 -m32 -m64 -mapp-regs -mno-app-regs @gol
758 -mfaster-structs -mno-faster-structs @gol
759 -mfpu -mno-fpu -mhard-float -msoft-float @gol
760 -mhard-quad-float -msoft-quad-float @gol
761 -mimpure-text -mno-impure-text -mlittle-endian @gol
762 -mstack-bias -mno-stack-bias @gol
763 -munaligned-doubles -mno-unaligned-doubles @gol
764 -mv8plus -mno-v8plus -mvis -mno-vis
765 -threads -pthreads -pthread}
768 @gccoptlist{-mwarn-reloc -merror-reloc @gol
769 -msafe-dma -munsafe-dma @gol
771 -msmall-mem -mlarge-mem -mstdmain @gol
772 -mfixed-range=@var{register-range}}
774 @emph{System V Options}
775 @gccoptlist{-Qy -Qn -YP,@var{paths} -Ym,@var{dir}}
778 @gccoptlist{-mlong-calls -mno-long-calls -mep -mno-ep @gol
779 -mprolog-function -mno-prolog-function -mspace @gol
780 -mtda=@var{n} -msda=@var{n} -mzda=@var{n} @gol
781 -mapp-regs -mno-app-regs @gol
782 -mdisable-callt -mno-disable-callt @gol
788 @gccoptlist{-mg -mgnu -munix}
790 @emph{VxWorks Options}
791 @gccoptlist{-mrtp -non-static -Bstatic -Bdynamic @gol
792 -Xbind-lazy -Xbind-now}
794 @emph{x86-64 Options}
795 See i386 and x86-64 Options.
797 @emph{Xstormy16 Options}
800 @emph{Xtensa Options}
801 @gccoptlist{-mconst16 -mno-const16 @gol
802 -mfused-madd -mno-fused-madd @gol
803 -mtext-section-literals -mno-text-section-literals @gol
804 -mtarget-align -mno-target-align @gol
805 -mlongcalls -mno-longcalls}
807 @emph{zSeries Options}
808 See S/390 and zSeries Options.
810 @item Code Generation Options
811 @xref{Code Gen Options,,Options for Code Generation Conventions}.
812 @gccoptlist{-fcall-saved-@var{reg} -fcall-used-@var{reg} @gol
813 -ffixed-@var{reg} -fexceptions @gol
814 -fnon-call-exceptions -funwind-tables @gol
815 -fasynchronous-unwind-tables @gol
816 -finhibit-size-directive -finstrument-functions @gol
817 -finstrument-functions-exclude-function-list=@var{sym},@var{sym},@dots{} @gol
818 -finstrument-functions-exclude-file-list=@var{file},@var{file},@dots{} @gol
819 -fno-common -fno-ident @gol
820 -fpcc-struct-return -fpic -fPIC -fpie -fPIE @gol
821 -fno-jump-tables @gol
822 -frecord-gcc-switches @gol
823 -freg-struct-return -fshort-enums @gol
824 -fshort-double -fshort-wchar @gol
825 -fverbose-asm -fpack-struct[=@var{n}] -fstack-check @gol
826 -fstack-limit-register=@var{reg} -fstack-limit-symbol=@var{sym} @gol
827 -fno-stack-limit -fargument-alias -fargument-noalias @gol
828 -fargument-noalias-global -fargument-noalias-anything @gol
829 -fleading-underscore -ftls-model=@var{model} @gol
830 -ftrapv -fwrapv -fbounds-check @gol
835 * Overall Options:: Controlling the kind of output:
836 an executable, object files, assembler files,
837 or preprocessed source.
838 * C Dialect Options:: Controlling the variant of C language compiled.
839 * C++ Dialect Options:: Variations on C++.
840 * Objective-C and Objective-C++ Dialect Options:: Variations on Objective-C
842 * Language Independent Options:: Controlling how diagnostics should be
844 * Warning Options:: How picky should the compiler be?
845 * Debugging Options:: Symbol tables, measurements, and debugging dumps.
846 * Optimize Options:: How much optimization?
847 * Preprocessor Options:: Controlling header files and macro definitions.
848 Also, getting dependency information for Make.
849 * Assembler Options:: Passing options to the assembler.
850 * Link Options:: Specifying libraries and so on.
851 * Directory Options:: Where to find header files and libraries.
852 Where to find the compiler executable files.
853 * Spec Files:: How to pass switches to sub-processes.
854 * Target Options:: Running a cross-compiler, or an old version of GCC.
857 @node Overall Options
858 @section Options Controlling the Kind of Output
860 Compilation can involve up to four stages: preprocessing, compilation
861 proper, assembly and linking, always in that order. GCC is capable of
862 preprocessing and compiling several files either into several
863 assembler input files, or into one assembler input file; then each
864 assembler input file produces an object file, and linking combines all
865 the object files (those newly compiled, and those specified as input)
866 into an executable file.
868 @cindex file name suffix
869 For any given input file, the file name suffix determines what kind of
874 C source code which must be preprocessed.
877 C source code which should not be preprocessed.
880 C++ source code which should not be preprocessed.
883 Objective-C source code. Note that you must link with the @file{libobjc}
884 library to make an Objective-C program work.
887 Objective-C source code which should not be preprocessed.
891 Objective-C++ source code. Note that you must link with the @file{libobjc}
892 library to make an Objective-C++ program work. Note that @samp{.M} refers
893 to a literal capital M@.
896 Objective-C++ source code which should not be preprocessed.
899 C, C++, Objective-C or Objective-C++ header file to be turned into a
904 @itemx @var{file}.cxx
905 @itemx @var{file}.cpp
906 @itemx @var{file}.CPP
907 @itemx @var{file}.c++
909 C++ source code which must be preprocessed. Note that in @samp{.cxx},
910 the last two letters must both be literally @samp{x}. Likewise,
911 @samp{.C} refers to a literal capital C@.
915 Objective-C++ source code which must be preprocessed.
918 Objective-C++ source code which should not be preprocessed.
923 @itemx @var{file}.hxx
924 @itemx @var{file}.hpp
925 @itemx @var{file}.HPP
926 @itemx @var{file}.h++
927 @itemx @var{file}.tcc
928 C++ header file to be turned into a precompiled header.
931 @itemx @var{file}.for
932 @itemx @var{file}.FOR
933 Fixed form Fortran source code which should not be preprocessed.
936 @itemx @var{file}.fpp
937 @itemx @var{file}.FPP
938 Fixed form Fortran source code which must be preprocessed (with the traditional
942 @itemx @var{file}.f95
943 Free form Fortran source code which should not be preprocessed.
946 @itemx @var{file}.F95
947 Free form Fortran source code which must be preprocessed (with the
948 traditional preprocessor).
950 @c FIXME: Descriptions of Java file types.
957 Ada source code file which contains a library unit declaration (a
958 declaration of a package, subprogram, or generic, or a generic
959 instantiation), or a library unit renaming declaration (a package,
960 generic, or subprogram renaming declaration). Such files are also
963 @itemx @var{file}.adb
964 Ada source code file containing a library unit body (a subprogram or
965 package body). Such files are also called @dfn{bodies}.
967 @c GCC also knows about some suffixes for languages not yet included:
979 Assembler code which must be preprocessed.
982 An object file to be fed straight into linking.
983 Any file name with no recognized suffix is treated this way.
987 You can specify the input language explicitly with the @option{-x} option:
990 @item -x @var{language}
991 Specify explicitly the @var{language} for the following input files
992 (rather than letting the compiler choose a default based on the file
993 name suffix). This option applies to all following input files until
994 the next @option{-x} option. Possible values for @var{language} are:
996 c c-header c-cpp-output
997 c++ c++-header c++-cpp-output
998 objective-c objective-c-header objective-c-cpp-output
999 objective-c++ objective-c++-header objective-c++-cpp-output
1000 assembler assembler-with-cpp
1007 Turn off any specification of a language, so that subsequent files are
1008 handled according to their file name suffixes (as they are if @option{-x}
1009 has not been used at all).
1011 @item -pass-exit-codes
1012 @opindex pass-exit-codes
1013 Normally the @command{gcc} program will exit with the code of 1 if any
1014 phase of the compiler returns a non-success return code. If you specify
1015 @option{-pass-exit-codes}, the @command{gcc} program will instead return with
1016 numerically highest error produced by any phase that returned an error
1017 indication. The C, C++, and Fortran frontends return 4, if an internal
1018 compiler error is encountered.
1021 If you only want some of the stages of compilation, you can use
1022 @option{-x} (or filename suffixes) to tell @command{gcc} where to start, and
1023 one of the options @option{-c}, @option{-S}, or @option{-E} to say where
1024 @command{gcc} is to stop. Note that some combinations (for example,
1025 @samp{-x cpp-output -E}) instruct @command{gcc} to do nothing at all.
1030 Compile or assemble the source files, but do not link. The linking
1031 stage simply is not done. The ultimate output is in the form of an
1032 object file for each source file.
1034 By default, the object file name for a source file is made by replacing
1035 the suffix @samp{.c}, @samp{.i}, @samp{.s}, etc., with @samp{.o}.
1037 Unrecognized input files, not requiring compilation or assembly, are
1042 Stop after the stage of compilation proper; do not assemble. The output
1043 is in the form of an assembler code file for each non-assembler input
1046 By default, the assembler file name for a source file is made by
1047 replacing the suffix @samp{.c}, @samp{.i}, etc., with @samp{.s}.
1049 Input files that don't require compilation are ignored.
1053 Stop after the preprocessing stage; do not run the compiler proper. The
1054 output is in the form of preprocessed source code, which is sent to the
1057 Input files which don't require preprocessing are ignored.
1059 @cindex output file option
1062 Place output in file @var{file}. This applies regardless to whatever
1063 sort of output is being produced, whether it be an executable file,
1064 an object file, an assembler file or preprocessed C code.
1066 If @option{-o} is not specified, the default is to put an executable
1067 file in @file{a.out}, the object file for
1068 @file{@var{source}.@var{suffix}} in @file{@var{source}.o}, its
1069 assembler file in @file{@var{source}.s}, a precompiled header file in
1070 @file{@var{source}.@var{suffix}.gch}, and all preprocessed C source on
1075 Print (on standard error output) the commands executed to run the stages
1076 of compilation. Also print the version number of the compiler driver
1077 program and of the preprocessor and the compiler proper.
1081 Like @option{-v} except the commands are not executed and all command
1082 arguments are quoted. This is useful for shell scripts to capture the
1083 driver-generated command lines.
1087 Use pipes rather than temporary files for communication between the
1088 various stages of compilation. This fails to work on some systems where
1089 the assembler is unable to read from a pipe; but the GNU assembler has
1094 If you are compiling multiple source files, this option tells the driver
1095 to pass all the source files to the compiler at once (for those
1096 languages for which the compiler can handle this). This will allow
1097 intermodule analysis (IMA) to be performed by the compiler. Currently the only
1098 language for which this is supported is C@. If you pass source files for
1099 multiple languages to the driver, using this option, the driver will invoke
1100 the compiler(s) that support IMA once each, passing each compiler all the
1101 source files appropriate for it. For those languages that do not support
1102 IMA this option will be ignored, and the compiler will be invoked once for
1103 each source file in that language. If you use this option in conjunction
1104 with @option{-save-temps}, the compiler will generate multiple
1106 (one for each source file), but only one (combined) @file{.o} or
1111 Print (on the standard output) a description of the command line options
1112 understood by @command{gcc}. If the @option{-v} option is also specified
1113 then @option{--help} will also be passed on to the various processes
1114 invoked by @command{gcc}, so that they can display the command line options
1115 they accept. If the @option{-Wextra} option has also been specified
1116 (prior to the @option{--help} option), then command line options which
1117 have no documentation associated with them will also be displayed.
1120 @opindex target-help
1121 Print (on the standard output) a description of target-specific command
1122 line options for each tool. For some targets extra target-specific
1123 information may also be printed.
1125 @item --help=@var{class}@r{[},@var{qualifier}@r{]}
1126 Print (on the standard output) a description of the command line
1127 options understood by the compiler that fit into a specific class.
1128 The class can be one of @samp{optimizers}, @samp{warnings}, @samp{target},
1129 @samp{params}, or @var{language}:
1132 @item @samp{optimizers}
1133 This will display all of the optimization options supported by the
1136 @item @samp{warnings}
1137 This will display all of the options controlling warning messages
1138 produced by the compiler.
1141 This will display target-specific options. Unlike the
1142 @option{--target-help} option however, target-specific options of the
1143 linker and assembler will not be displayed. This is because those
1144 tools do not currently support the extended @option{--help=} syntax.
1147 This will display the values recognized by the @option{--param}
1150 @item @var{language}
1151 This will display the options supported for @var{language}, where
1152 @var{language} is the name of one of the languages supported in this
1156 This will display the options that are common to all languages.
1159 It is possible to further refine the output of the @option{--help=}
1160 option by adding a comma separated list of qualifiers after the
1161 class. These can be any from the following list:
1164 @item @samp{undocumented}
1165 Display only those options which are undocumented.
1168 Display options which take an argument that appears after an equal
1169 sign in the same continuous piece of text, such as:
1170 @samp{--help=target}.
1172 @item @samp{separate}
1173 Display options which take an argument that appears as a separate word
1174 following the original option, such as: @samp{-o output-file}.
1177 Thus for example to display all the undocumented target-specific
1178 switches supported by the compiler the following can be used:
1181 --help=target,undocumented
1184 The sense of a qualifier can be inverted by prefixing it with the
1185 @var{^} character, so for example to display all binary warning
1186 options (i.e., ones that are either on or off and that do not take an
1187 argument), which have a description the following can be used:
1190 --help=warnings,^joined,^undocumented
1193 A class can also be used as a qualifier, although this usually
1194 restricts the output by so much that there is nothing to display. One
1195 case where it does work however is when one of the classes is
1196 @var{target}. So for example to display all the target-specific
1197 optimization options the following can be used:
1200 --help=target,optimizers
1203 The @option{--help=} option can be repeated on the command line. Each
1204 successive use will display its requested class of options, skipping
1205 those that have already been displayed.
1207 If the @option{-Q} option appears on the command line before the
1208 @option{--help=} option, then the descriptive text displayed by
1209 @option{--help=} is changed. Instead of describing the displayed
1210 options, an indication is given as to whether the option is enabled,
1211 disabled or set to a specific value (assuming that the compiler
1212 knows this at the point where the @option{--help=} option is used).
1214 Here is a truncated example from the ARM port of @command{gcc}:
1217 % gcc -Q -mabi=2 --help=target -c
1218 The following options are target specific:
1220 -mabort-on-noreturn [disabled]
1224 The output is sensitive to the effects of previous command line
1225 options, so for example it is possible to find out which optimizations
1226 are enabled at @option{-O2} by using:
1229 -O2 --help=optimizers
1232 Alternatively you can discover which binary optimizations are enabled
1233 by @option{-O3} by using:
1236 gcc -c -Q -O3 --help=optimizers > /tmp/O3-opts
1237 gcc -c -Q -O2 --help=optimizers > /tmp/O2-opts
1238 diff /tmp/O2-opts /tmp/O3-opts | grep enabled
1243 Display the version number and copyrights of the invoked GCC@.
1245 @include @value{srcdir}/../libiberty/at-file.texi
1249 @section Compiling C++ Programs
1251 @cindex suffixes for C++ source
1252 @cindex C++ source file suffixes
1253 C++ source files conventionally use one of the suffixes @samp{.C},
1254 @samp{.cc}, @samp{.cpp}, @samp{.CPP}, @samp{.c++}, @samp{.cp}, or
1255 @samp{.cxx}; C++ header files often use @samp{.hh}, @samp{.hpp},
1256 @samp{.H}, or (for shared template code) @samp{.tcc}; and
1257 preprocessed C++ files use the suffix @samp{.ii}. GCC recognizes
1258 files with these names and compiles them as C++ programs even if you
1259 call the compiler the same way as for compiling C programs (usually
1260 with the name @command{gcc}).
1264 However, the use of @command{gcc} does not add the C++ library.
1265 @command{g++} is a program that calls GCC and treats @samp{.c},
1266 @samp{.h} and @samp{.i} files as C++ source files instead of C source
1267 files unless @option{-x} is used, and automatically specifies linking
1268 against the C++ library. This program is also useful when
1269 precompiling a C header file with a @samp{.h} extension for use in C++
1270 compilations. On many systems, @command{g++} is also installed with
1271 the name @command{c++}.
1273 @cindex invoking @command{g++}
1274 When you compile C++ programs, you may specify many of the same
1275 command-line options that you use for compiling programs in any
1276 language; or command-line options meaningful for C and related
1277 languages; or options that are meaningful only for C++ programs.
1278 @xref{C Dialect Options,,Options Controlling C Dialect}, for
1279 explanations of options for languages related to C@.
1280 @xref{C++ Dialect Options,,Options Controlling C++ Dialect}, for
1281 explanations of options that are meaningful only for C++ programs.
1283 @node C Dialect Options
1284 @section Options Controlling C Dialect
1285 @cindex dialect options
1286 @cindex language dialect options
1287 @cindex options, dialect
1289 The following options control the dialect of C (or languages derived
1290 from C, such as C++, Objective-C and Objective-C++) that the compiler
1294 @cindex ANSI support
1298 In C mode, this is equivalent to @samp{-std=c89}. In C++ mode, it is
1299 equivalent to @samp{-std=c++98}.
1301 This turns off certain features of GCC that are incompatible with ISO
1302 C90 (when compiling C code), or of standard C++ (when compiling C++ code),
1303 such as the @code{asm} and @code{typeof} keywords, and
1304 predefined macros such as @code{unix} and @code{vax} that identify the
1305 type of system you are using. It also enables the undesirable and
1306 rarely used ISO trigraph feature. For the C compiler,
1307 it disables recognition of C++ style @samp{//} comments as well as
1308 the @code{inline} keyword.
1310 The alternate keywords @code{__asm__}, @code{__extension__},
1311 @code{__inline__} and @code{__typeof__} continue to work despite
1312 @option{-ansi}. You would not want to use them in an ISO C program, of
1313 course, but it is useful to put them in header files that might be included
1314 in compilations done with @option{-ansi}. Alternate predefined macros
1315 such as @code{__unix__} and @code{__vax__} are also available, with or
1316 without @option{-ansi}.
1318 The @option{-ansi} option does not cause non-ISO programs to be
1319 rejected gratuitously. For that, @option{-pedantic} is required in
1320 addition to @option{-ansi}. @xref{Warning Options}.
1322 The macro @code{__STRICT_ANSI__} is predefined when the @option{-ansi}
1323 option is used. Some header files may notice this macro and refrain
1324 from declaring certain functions or defining certain macros that the
1325 ISO standard doesn't call for; this is to avoid interfering with any
1326 programs that might use these names for other things.
1328 Functions that would normally be built in but do not have semantics
1329 defined by ISO C (such as @code{alloca} and @code{ffs}) are not built-in
1330 functions when @option{-ansi} is used. @xref{Other Builtins,,Other
1331 built-in functions provided by GCC}, for details of the functions
1336 Determine the language standard. @xref{Standards,,Language Standards
1337 Supported by GCC}, for details of these standard versions. This option
1338 is currently only supported when compiling C or C++.
1340 The compiler can accept several base standards, such as @samp{c89} or
1341 @samp{c++98}, and GNU dialects of those standards, such as
1342 @samp{gnu89} or @samp{gnu++98}. By specifing a base standard, the
1343 compiler will accept all programs following that standard and those
1344 using GNU extensions that do not contradict it. For example,
1345 @samp{-std=c89} turns off certain features of GCC that are
1346 incompatible with ISO C90, such as the @code{asm} and @code{typeof}
1347 keywords, but not other GNU extensions that do not have a meaning in
1348 ISO C90, such as omitting the middle term of a @code{?:}
1349 expression. On the other hand, by specifing a GNU dialect of a
1350 standard, all features the compiler support are enabled, even when
1351 those features change the meaning of the base standard and some
1352 strict-conforming programs may be rejected. The particular standard
1353 is used by @option{-pedantic} to identify which features are GNU
1354 extensions given that version of the standard. For example
1355 @samp{-std=gnu89 -pedantic} would warn about C++ style @samp{//}
1356 comments, while @samp{-std=gnu99 -pedantic} would not.
1358 A value for this option must be provided; possible values are
1363 Support all ISO C90 programs (certain GNU extensions that conflict
1364 with ISO C90 are disabled). Same as @option{-ansi} for C code.
1366 @item iso9899:199409
1367 ISO C90 as modified in amendment 1.
1373 ISO C99. Note that this standard is not yet fully supported; see
1374 @w{@uref{http://gcc.gnu.org/c99status.html}} for more information. The
1375 names @samp{c9x} and @samp{iso9899:199x} are deprecated.
1378 GNU dialect of ISO C90 (including some C99 features). This
1379 is the default for C code.
1383 GNU dialect of ISO C99. When ISO C99 is fully implemented in GCC,
1384 this will become the default. The name @samp{gnu9x} is deprecated.
1387 The 1998 ISO C++ standard plus amendments. Same as @option{-ansi} for
1391 GNU dialect of @option{-std=c++98}. This is the default for
1395 The working draft of the upcoming ISO C++0x standard. This option
1396 enables experimental features that are likely to be included in
1397 C++0x. The working draft is constantly changing, and any feature that is
1398 enabled by this flag may be removed from future versions of GCC if it is
1399 not part of the C++0x standard.
1402 GNU dialect of @option{-std=c++0x}. This option enables
1403 experimental features that may be removed in future versions of GCC.
1406 @item -fgnu89-inline
1407 @opindex fgnu89-inline
1408 The option @option{-fgnu89-inline} tells GCC to use the traditional
1409 GNU semantics for @code{inline} functions when in C99 mode.
1410 @xref{Inline,,An Inline Function is As Fast As a Macro}. This option
1411 is accepted and ignored by GCC versions 4.1.3 up to but not including
1412 4.3. In GCC versions 4.3 and later it changes the behavior of GCC in
1413 C99 mode. Using this option is roughly equivalent to adding the
1414 @code{gnu_inline} function attribute to all inline functions
1415 (@pxref{Function Attributes}).
1417 The option @option{-fno-gnu89-inline} explicitly tells GCC to use the
1418 C99 semantics for @code{inline} when in C99 or gnu99 mode (i.e., it
1419 specifies the default behavior). This option was first supported in
1420 GCC 4.3. This option is not supported in C89 or gnu89 mode.
1422 The preprocessor macros @code{__GNUC_GNU_INLINE__} and
1423 @code{__GNUC_STDC_INLINE__} may be used to check which semantics are
1424 in effect for @code{inline} functions. @xref{Common Predefined
1425 Macros,,,cpp,The C Preprocessor}.
1427 @item -aux-info @var{filename}
1429 Output to the given filename prototyped declarations for all functions
1430 declared and/or defined in a translation unit, including those in header
1431 files. This option is silently ignored in any language other than C@.
1433 Besides declarations, the file indicates, in comments, the origin of
1434 each declaration (source file and line), whether the declaration was
1435 implicit, prototyped or unprototyped (@samp{I}, @samp{N} for new or
1436 @samp{O} for old, respectively, in the first character after the line
1437 number and the colon), and whether it came from a declaration or a
1438 definition (@samp{C} or @samp{F}, respectively, in the following
1439 character). In the case of function definitions, a K&R-style list of
1440 arguments followed by their declarations is also provided, inside
1441 comments, after the declaration.
1445 Do not recognize @code{asm}, @code{inline} or @code{typeof} as a
1446 keyword, so that code can use these words as identifiers. You can use
1447 the keywords @code{__asm__}, @code{__inline__} and @code{__typeof__}
1448 instead. @option{-ansi} implies @option{-fno-asm}.
1450 In C++, this switch only affects the @code{typeof} keyword, since
1451 @code{asm} and @code{inline} are standard keywords. You may want to
1452 use the @option{-fno-gnu-keywords} flag instead, which has the same
1453 effect. In C99 mode (@option{-std=c99} or @option{-std=gnu99}), this
1454 switch only affects the @code{asm} and @code{typeof} keywords, since
1455 @code{inline} is a standard keyword in ISO C99.
1458 @itemx -fno-builtin-@var{function}
1459 @opindex fno-builtin
1460 @cindex built-in functions
1461 Don't recognize built-in functions that do not begin with
1462 @samp{__builtin_} as prefix. @xref{Other Builtins,,Other built-in
1463 functions provided by GCC}, for details of the functions affected,
1464 including those which are not built-in functions when @option{-ansi} or
1465 @option{-std} options for strict ISO C conformance are used because they
1466 do not have an ISO standard meaning.
1468 GCC normally generates special code to handle certain built-in functions
1469 more efficiently; for instance, calls to @code{alloca} may become single
1470 instructions that adjust the stack directly, and calls to @code{memcpy}
1471 may become inline copy loops. The resulting code is often both smaller
1472 and faster, but since the function calls no longer appear as such, you
1473 cannot set a breakpoint on those calls, nor can you change the behavior
1474 of the functions by linking with a different library. In addition,
1475 when a function is recognized as a built-in function, GCC may use
1476 information about that function to warn about problems with calls to
1477 that function, or to generate more efficient code, even if the
1478 resulting code still contains calls to that function. For example,
1479 warnings are given with @option{-Wformat} for bad calls to
1480 @code{printf}, when @code{printf} is built in, and @code{strlen} is
1481 known not to modify global memory.
1483 With the @option{-fno-builtin-@var{function}} option
1484 only the built-in function @var{function} is
1485 disabled. @var{function} must not begin with @samp{__builtin_}. If a
1486 function is named this is not built-in in this version of GCC, this
1487 option is ignored. There is no corresponding
1488 @option{-fbuiltin-@var{function}} option; if you wish to enable
1489 built-in functions selectively when using @option{-fno-builtin} or
1490 @option{-ffreestanding}, you may define macros such as:
1493 #define abs(n) __builtin_abs ((n))
1494 #define strcpy(d, s) __builtin_strcpy ((d), (s))
1499 @cindex hosted environment
1501 Assert that compilation takes place in a hosted environment. This implies
1502 @option{-fbuiltin}. A hosted environment is one in which the
1503 entire standard library is available, and in which @code{main} has a return
1504 type of @code{int}. Examples are nearly everything except a kernel.
1505 This is equivalent to @option{-fno-freestanding}.
1507 @item -ffreestanding
1508 @opindex ffreestanding
1509 @cindex hosted environment
1511 Assert that compilation takes place in a freestanding environment. This
1512 implies @option{-fno-builtin}. A freestanding environment
1513 is one in which the standard library may not exist, and program startup may
1514 not necessarily be at @code{main}. The most obvious example is an OS kernel.
1515 This is equivalent to @option{-fno-hosted}.
1517 @xref{Standards,,Language Standards Supported by GCC}, for details of
1518 freestanding and hosted environments.
1522 @cindex openmp parallel
1523 Enable handling of OpenMP directives @code{#pragma omp} in C/C++ and
1524 @code{!$omp} in Fortran. When @option{-fopenmp} is specified, the
1525 compiler generates parallel code according to the OpenMP Application
1526 Program Interface v2.5 @w{@uref{http://www.openmp.org/}}. This option
1527 implies @option{-pthread}, and thus is only supported on targets that
1528 have support for @option{-pthread}.
1530 @item -fms-extensions
1531 @opindex fms-extensions
1532 Accept some non-standard constructs used in Microsoft header files.
1534 Some cases of unnamed fields in structures and unions are only
1535 accepted with this option. @xref{Unnamed Fields,,Unnamed struct/union
1536 fields within structs/unions}, for details.
1540 Support ISO C trigraphs. The @option{-ansi} option (and @option{-std}
1541 options for strict ISO C conformance) implies @option{-trigraphs}.
1543 @item -no-integrated-cpp
1544 @opindex no-integrated-cpp
1545 Performs a compilation in two passes: preprocessing and compiling. This
1546 option allows a user supplied "cc1", "cc1plus", or "cc1obj" via the
1547 @option{-B} option. The user supplied compilation step can then add in
1548 an additional preprocessing step after normal preprocessing but before
1549 compiling. The default is to use the integrated cpp (internal cpp)
1551 The semantics of this option will change if "cc1", "cc1plus", and
1552 "cc1obj" are merged.
1554 @cindex traditional C language
1555 @cindex C language, traditional
1557 @itemx -traditional-cpp
1558 @opindex traditional-cpp
1559 @opindex traditional
1560 Formerly, these options caused GCC to attempt to emulate a pre-standard
1561 C compiler. They are now only supported with the @option{-E} switch.
1562 The preprocessor continues to support a pre-standard mode. See the GNU
1563 CPP manual for details.
1565 @item -fcond-mismatch
1566 @opindex fcond-mismatch
1567 Allow conditional expressions with mismatched types in the second and
1568 third arguments. The value of such an expression is void. This option
1569 is not supported for C++.
1571 @item -flax-vector-conversions
1572 @opindex flax-vector-conversions
1573 Allow implicit conversions between vectors with differing numbers of
1574 elements and/or incompatible element types. This option should not be
1577 @item -funsigned-char
1578 @opindex funsigned-char
1579 Let the type @code{char} be unsigned, like @code{unsigned char}.
1581 Each kind of machine has a default for what @code{char} should
1582 be. It is either like @code{unsigned char} by default or like
1583 @code{signed char} by default.
1585 Ideally, a portable program should always use @code{signed char} or
1586 @code{unsigned char} when it depends on the signedness of an object.
1587 But many programs have been written to use plain @code{char} and
1588 expect it to be signed, or expect it to be unsigned, depending on the
1589 machines they were written for. This option, and its inverse, let you
1590 make such a program work with the opposite default.
1592 The type @code{char} is always a distinct type from each of
1593 @code{signed char} or @code{unsigned char}, even though its behavior
1594 is always just like one of those two.
1597 @opindex fsigned-char
1598 Let the type @code{char} be signed, like @code{signed char}.
1600 Note that this is equivalent to @option{-fno-unsigned-char}, which is
1601 the negative form of @option{-funsigned-char}. Likewise, the option
1602 @option{-fno-signed-char} is equivalent to @option{-funsigned-char}.
1604 @item -fsigned-bitfields
1605 @itemx -funsigned-bitfields
1606 @itemx -fno-signed-bitfields
1607 @itemx -fno-unsigned-bitfields
1608 @opindex fsigned-bitfields
1609 @opindex funsigned-bitfields
1610 @opindex fno-signed-bitfields
1611 @opindex fno-unsigned-bitfields
1612 These options control whether a bit-field is signed or unsigned, when the
1613 declaration does not use either @code{signed} or @code{unsigned}. By
1614 default, such a bit-field is signed, because this is consistent: the
1615 basic integer types such as @code{int} are signed types.
1618 @node C++ Dialect Options
1619 @section Options Controlling C++ Dialect
1621 @cindex compiler options, C++
1622 @cindex C++ options, command line
1623 @cindex options, C++
1624 This section describes the command-line options that are only meaningful
1625 for C++ programs; but you can also use most of the GNU compiler options
1626 regardless of what language your program is in. For example, you
1627 might compile a file @code{firstClass.C} like this:
1630 g++ -g -frepo -O -c firstClass.C
1634 In this example, only @option{-frepo} is an option meant
1635 only for C++ programs; you can use the other options with any
1636 language supported by GCC@.
1638 Here is a list of options that are @emph{only} for compiling C++ programs:
1642 @item -fabi-version=@var{n}
1643 @opindex fabi-version
1644 Use version @var{n} of the C++ ABI@. Version 2 is the version of the
1645 C++ ABI that first appeared in G++ 3.4. Version 1 is the version of
1646 the C++ ABI that first appeared in G++ 3.2. Version 0 will always be
1647 the version that conforms most closely to the C++ ABI specification.
1648 Therefore, the ABI obtained using version 0 will change as ABI bugs
1651 The default is version 2.
1653 @item -fno-access-control
1654 @opindex fno-access-control
1655 Turn off all access checking. This switch is mainly useful for working
1656 around bugs in the access control code.
1660 Check that the pointer returned by @code{operator new} is non-null
1661 before attempting to modify the storage allocated. This check is
1662 normally unnecessary because the C++ standard specifies that
1663 @code{operator new} will only return @code{0} if it is declared
1664 @samp{throw()}, in which case the compiler will always check the
1665 return value even without this option. In all other cases, when
1666 @code{operator new} has a non-empty exception specification, memory
1667 exhaustion is signalled by throwing @code{std::bad_alloc}. See also
1668 @samp{new (nothrow)}.
1670 @item -fconserve-space
1671 @opindex fconserve-space
1672 Put uninitialized or runtime-initialized global variables into the
1673 common segment, as C does. This saves space in the executable at the
1674 cost of not diagnosing duplicate definitions. If you compile with this
1675 flag and your program mysteriously crashes after @code{main()} has
1676 completed, you may have an object that is being destroyed twice because
1677 two definitions were merged.
1679 This option is no longer useful on most targets, now that support has
1680 been added for putting variables into BSS without making them common.
1682 @item -ffriend-injection
1683 @opindex ffriend-injection
1684 Inject friend functions into the enclosing namespace, so that they are
1685 visible outside the scope of the class in which they are declared.
1686 Friend functions were documented to work this way in the old Annotated
1687 C++ Reference Manual, and versions of G++ before 4.1 always worked
1688 that way. However, in ISO C++ a friend function which is not declared
1689 in an enclosing scope can only be found using argument dependent
1690 lookup. This option causes friends to be injected as they were in
1693 This option is for compatibility, and may be removed in a future
1696 @item -fno-elide-constructors
1697 @opindex fno-elide-constructors
1698 The C++ standard allows an implementation to omit creating a temporary
1699 which is only used to initialize another object of the same type.
1700 Specifying this option disables that optimization, and forces G++ to
1701 call the copy constructor in all cases.
1703 @item -fno-enforce-eh-specs
1704 @opindex fno-enforce-eh-specs
1705 Don't generate code to check for violation of exception specifications
1706 at runtime. This option violates the C++ standard, but may be useful
1707 for reducing code size in production builds, much like defining
1708 @samp{NDEBUG}. This does not give user code permission to throw
1709 exceptions in violation of the exception specifications; the compiler
1710 will still optimize based on the specifications, so throwing an
1711 unexpected exception will result in undefined behavior.
1714 @itemx -fno-for-scope
1716 @opindex fno-for-scope
1717 If @option{-ffor-scope} is specified, the scope of variables declared in
1718 a @i{for-init-statement} is limited to the @samp{for} loop itself,
1719 as specified by the C++ standard.
1720 If @option{-fno-for-scope} is specified, the scope of variables declared in
1721 a @i{for-init-statement} extends to the end of the enclosing scope,
1722 as was the case in old versions of G++, and other (traditional)
1723 implementations of C++.
1725 The default if neither flag is given to follow the standard,
1726 but to allow and give a warning for old-style code that would
1727 otherwise be invalid, or have different behavior.
1729 @item -fno-gnu-keywords
1730 @opindex fno-gnu-keywords
1731 Do not recognize @code{typeof} as a keyword, so that code can use this
1732 word as an identifier. You can use the keyword @code{__typeof__} instead.
1733 @option{-ansi} implies @option{-fno-gnu-keywords}.
1735 @item -fno-implicit-templates
1736 @opindex fno-implicit-templates
1737 Never emit code for non-inline templates which are instantiated
1738 implicitly (i.e.@: by use); only emit code for explicit instantiations.
1739 @xref{Template Instantiation}, for more information.
1741 @item -fno-implicit-inline-templates
1742 @opindex fno-implicit-inline-templates
1743 Don't emit code for implicit instantiations of inline templates, either.
1744 The default is to handle inlines differently so that compiles with and
1745 without optimization will need the same set of explicit instantiations.
1747 @item -fno-implement-inlines
1748 @opindex fno-implement-inlines
1749 To save space, do not emit out-of-line copies of inline functions
1750 controlled by @samp{#pragma implementation}. This will cause linker
1751 errors if these functions are not inlined everywhere they are called.
1753 @item -fms-extensions
1754 @opindex fms-extensions
1755 Disable pedantic warnings about constructs used in MFC, such as implicit
1756 int and getting a pointer to member function via non-standard syntax.
1758 @item -fno-nonansi-builtins
1759 @opindex fno-nonansi-builtins
1760 Disable built-in declarations of functions that are not mandated by
1761 ANSI/ISO C@. These include @code{ffs}, @code{alloca}, @code{_exit},
1762 @code{index}, @code{bzero}, @code{conjf}, and other related functions.
1764 @item -fno-operator-names
1765 @opindex fno-operator-names
1766 Do not treat the operator name keywords @code{and}, @code{bitand},
1767 @code{bitor}, @code{compl}, @code{not}, @code{or} and @code{xor} as
1768 synonyms as keywords.
1770 @item -fno-optional-diags
1771 @opindex fno-optional-diags
1772 Disable diagnostics that the standard says a compiler does not need to
1773 issue. Currently, the only such diagnostic issued by G++ is the one for
1774 a name having multiple meanings within a class.
1777 @opindex fpermissive
1778 Downgrade some diagnostics about nonconformant code from errors to
1779 warnings. Thus, using @option{-fpermissive} will allow some
1780 nonconforming code to compile.
1784 Enable automatic template instantiation at link time. This option also
1785 implies @option{-fno-implicit-templates}. @xref{Template
1786 Instantiation}, for more information.
1790 Disable generation of information about every class with virtual
1791 functions for use by the C++ runtime type identification features
1792 (@samp{dynamic_cast} and @samp{typeid}). If you don't use those parts
1793 of the language, you can save some space by using this flag. Note that
1794 exception handling uses the same information, but it will generate it as
1795 needed. The @samp{dynamic_cast} operator can still be used for casts that
1796 do not require runtime type information, i.e.@: casts to @code{void *} or to
1797 unambiguous base classes.
1801 Emit statistics about front-end processing at the end of the compilation.
1802 This information is generally only useful to the G++ development team.
1804 @item -ftemplate-depth-@var{n}
1805 @opindex ftemplate-depth
1806 Set the maximum instantiation depth for template classes to @var{n}.
1807 A limit on the template instantiation depth is needed to detect
1808 endless recursions during template class instantiation. ANSI/ISO C++
1809 conforming programs must not rely on a maximum depth greater than 17.
1811 @item -fno-threadsafe-statics
1812 @opindex fno-threadsafe-statics
1813 Do not emit the extra code to use the routines specified in the C++
1814 ABI for thread-safe initialization of local statics. You can use this
1815 option to reduce code size slightly in code that doesn't need to be
1818 @item -fuse-cxa-atexit
1819 @opindex fuse-cxa-atexit
1820 Register destructors for objects with static storage duration with the
1821 @code{__cxa_atexit} function rather than the @code{atexit} function.
1822 This option is required for fully standards-compliant handling of static
1823 destructors, but will only work if your C library supports
1824 @code{__cxa_atexit}.
1826 @item -fno-use-cxa-get-exception-ptr
1827 @opindex fno-use-cxa-get-exception-ptr
1828 Don't use the @code{__cxa_get_exception_ptr} runtime routine. This
1829 will cause @code{std::uncaught_exception} to be incorrect, but is necessary
1830 if the runtime routine is not available.
1832 @item -fvisibility-inlines-hidden
1833 @opindex fvisibility-inlines-hidden
1834 This switch declares that the user does not attempt to compare
1835 pointers to inline methods where the addresses of the two functions
1836 were taken in different shared objects.
1838 The effect of this is that GCC may, effectively, mark inline methods with
1839 @code{__attribute__ ((visibility ("hidden")))} so that they do not
1840 appear in the export table of a DSO and do not require a PLT indirection
1841 when used within the DSO@. Enabling this option can have a dramatic effect
1842 on load and link times of a DSO as it massively reduces the size of the
1843 dynamic export table when the library makes heavy use of templates.
1845 The behavior of this switch is not quite the same as marking the
1846 methods as hidden directly, because it does not affect static variables
1847 local to the function or cause the compiler to deduce that
1848 the function is defined in only one shared object.
1850 You may mark a method as having a visibility explicitly to negate the
1851 effect of the switch for that method. For example, if you do want to
1852 compare pointers to a particular inline method, you might mark it as
1853 having default visibility. Marking the enclosing class with explicit
1854 visibility will have no effect.
1856 Explicitly instantiated inline methods are unaffected by this option
1857 as their linkage might otherwise cross a shared library boundary.
1858 @xref{Template Instantiation}.
1860 @item -fvisibility-ms-compat
1861 @opindex fvisibility-ms-compat
1862 This flag attempts to use visibility settings to make GCC's C++
1863 linkage model compatible with that of Microsoft Visual Studio.
1865 The flag makes these changes to GCC's linkage model:
1869 It sets the default visibility to @code{hidden}, like
1870 @option{-fvisibility=hidden}.
1873 Types, but not their members, are not hidden by default.
1876 The One Definition Rule is relaxed for types without explicit
1877 visibility specifications which are defined in more than one different
1878 shared object: those declarations are permitted if they would have
1879 been permitted when this option was not used.
1882 In new code it is better to use @option{-fvisibility=hidden} and
1883 export those classes which are intended to be externally visible.
1884 Unfortunately it is possible for code to rely, perhaps accidentally,
1885 on the Visual Studio behavior.
1887 Among the consequences of these changes are that static data members
1888 of the same type with the same name but defined in different shared
1889 objects will be different, so changing one will not change the other;
1890 and that pointers to function members defined in different shared
1891 objects may not compare equal. When this flag is given, it is a
1892 violation of the ODR to define types with the same name differently.
1896 Do not use weak symbol support, even if it is provided by the linker.
1897 By default, G++ will use weak symbols if they are available. This
1898 option exists only for testing, and should not be used by end-users;
1899 it will result in inferior code and has no benefits. This option may
1900 be removed in a future release of G++.
1904 Do not search for header files in the standard directories specific to
1905 C++, but do still search the other standard directories. (This option
1906 is used when building the C++ library.)
1909 In addition, these optimization, warning, and code generation options
1910 have meanings only for C++ programs:
1913 @item -fno-default-inline
1914 @opindex fno-default-inline
1915 Do not assume @samp{inline} for functions defined inside a class scope.
1916 @xref{Optimize Options,,Options That Control Optimization}. Note that these
1917 functions will have linkage like inline functions; they just won't be
1920 @item -Wabi @r{(C++ and Objective-C++ only)}
1923 Warn when G++ generates code that is probably not compatible with the
1924 vendor-neutral C++ ABI@. Although an effort has been made to warn about
1925 all such cases, there are probably some cases that are not warned about,
1926 even though G++ is generating incompatible code. There may also be
1927 cases where warnings are emitted even though the code that is generated
1930 You should rewrite your code to avoid these warnings if you are
1931 concerned about the fact that code generated by G++ may not be binary
1932 compatible with code generated by other compilers.
1934 The known incompatibilities at this point include:
1939 Incorrect handling of tail-padding for bit-fields. G++ may attempt to
1940 pack data into the same byte as a base class. For example:
1943 struct A @{ virtual void f(); int f1 : 1; @};
1944 struct B : public A @{ int f2 : 1; @};
1948 In this case, G++ will place @code{B::f2} into the same byte
1949 as@code{A::f1}; other compilers will not. You can avoid this problem
1950 by explicitly padding @code{A} so that its size is a multiple of the
1951 byte size on your platform; that will cause G++ and other compilers to
1952 layout @code{B} identically.
1955 Incorrect handling of tail-padding for virtual bases. G++ does not use
1956 tail padding when laying out virtual bases. For example:
1959 struct A @{ virtual void f(); char c1; @};
1960 struct B @{ B(); char c2; @};
1961 struct C : public A, public virtual B @{@};
1965 In this case, G++ will not place @code{B} into the tail-padding for
1966 @code{A}; other compilers will. You can avoid this problem by
1967 explicitly padding @code{A} so that its size is a multiple of its
1968 alignment (ignoring virtual base classes); that will cause G++ and other
1969 compilers to layout @code{C} identically.
1972 Incorrect handling of bit-fields with declared widths greater than that
1973 of their underlying types, when the bit-fields appear in a union. For
1977 union U @{ int i : 4096; @};
1981 Assuming that an @code{int} does not have 4096 bits, G++ will make the
1982 union too small by the number of bits in an @code{int}.
1985 Empty classes can be placed at incorrect offsets. For example:
1995 struct C : public B, public A @{@};
1999 G++ will place the @code{A} base class of @code{C} at a nonzero offset;
2000 it should be placed at offset zero. G++ mistakenly believes that the
2001 @code{A} data member of @code{B} is already at offset zero.
2004 Names of template functions whose types involve @code{typename} or
2005 template template parameters can be mangled incorrectly.
2008 template <typename Q>
2009 void f(typename Q::X) @{@}
2011 template <template <typename> class Q>
2012 void f(typename Q<int>::X) @{@}
2016 Instantiations of these templates may be mangled incorrectly.
2020 @item -Wctor-dtor-privacy @r{(C++ and Objective-C++ only)}
2021 @opindex Wctor-dtor-privacy
2022 @opindex Wno-ctor-dtor-privacy
2023 Warn when a class seems unusable because all the constructors or
2024 destructors in that class are private, and it has neither friends nor
2025 public static member functions.
2027 @item -Wnon-virtual-dtor @r{(C++ and Objective-C++ only)}
2028 @opindex Wnon-virtual-dtor
2029 @opindex Wno-non-virtual-dtor
2030 Warn when a class has virtual functions and accessible non-virtual
2031 destructor, in which case it would be possible but unsafe to delete
2032 an instance of a derived class through a pointer to the base class.
2033 This warning is also enabled if -Weffc++ is specified.
2035 @item -Wreorder @r{(C++ and Objective-C++ only)}
2037 @opindex Wno-reorder
2038 @cindex reordering, warning
2039 @cindex warning for reordering of member initializers
2040 Warn when the order of member initializers given in the code does not
2041 match the order in which they must be executed. For instance:
2047 A(): j (0), i (1) @{ @}
2051 The compiler will rearrange the member initializers for @samp{i}
2052 and @samp{j} to match the declaration order of the members, emitting
2053 a warning to that effect. This warning is enabled by @option{-Wall}.
2056 The following @option{-W@dots{}} options are not affected by @option{-Wall}.
2059 @item -Weffc++ @r{(C++ and Objective-C++ only)}
2062 Warn about violations of the following style guidelines from Scott Meyers'
2063 @cite{Effective C++} book:
2067 Item 11: Define a copy constructor and an assignment operator for classes
2068 with dynamically allocated memory.
2071 Item 12: Prefer initialization to assignment in constructors.
2074 Item 14: Make destructors virtual in base classes.
2077 Item 15: Have @code{operator=} return a reference to @code{*this}.
2080 Item 23: Don't try to return a reference when you must return an object.
2084 Also warn about violations of the following style guidelines from
2085 Scott Meyers' @cite{More Effective C++} book:
2089 Item 6: Distinguish between prefix and postfix forms of increment and
2090 decrement operators.
2093 Item 7: Never overload @code{&&}, @code{||}, or @code{,}.
2097 When selecting this option, be aware that the standard library
2098 headers do not obey all of these guidelines; use @samp{grep -v}
2099 to filter out those warnings.
2101 @item -Wno-deprecated @r{(C++ and Objective-C++ only)}
2102 @opindex Wno-deprecated
2103 @opindex Wdeprecated
2104 Do not warn about usage of deprecated features. @xref{Deprecated Features}.
2106 @item -Wstrict-null-sentinel @r{(C++ and Objective-C++ only)}
2107 @opindex Wstrict-null-sentinel
2108 @opindex Wno-strict-null-sentinel
2109 Warn also about the use of an uncasted @code{NULL} as sentinel. When
2110 compiling only with GCC this is a valid sentinel, as @code{NULL} is defined
2111 to @code{__null}. Although it is a null pointer constant not a null pointer,
2112 it is guaranteed to of the same size as a pointer. But this use is
2113 not portable across different compilers.
2115 @item -Wno-non-template-friend @r{(C++ and Objective-C++ only)}
2116 @opindex Wno-non-template-friend
2117 @opindex Wnon-template-friend
2118 Disable warnings when non-templatized friend functions are declared
2119 within a template. Since the advent of explicit template specification
2120 support in G++, if the name of the friend is an unqualified-id (i.e.,
2121 @samp{friend foo(int)}), the C++ language specification demands that the
2122 friend declare or define an ordinary, nontemplate function. (Section
2123 14.5.3). Before G++ implemented explicit specification, unqualified-ids
2124 could be interpreted as a particular specialization of a templatized
2125 function. Because this non-conforming behavior is no longer the default
2126 behavior for G++, @option{-Wnon-template-friend} allows the compiler to
2127 check existing code for potential trouble spots and is on by default.
2128 This new compiler behavior can be turned off with
2129 @option{-Wno-non-template-friend} which keeps the conformant compiler code
2130 but disables the helpful warning.
2132 @item -Wold-style-cast @r{(C++ and Objective-C++ only)}
2133 @opindex Wold-style-cast
2134 @opindex Wno-old-style-cast
2135 Warn if an old-style (C-style) cast to a non-void type is used within
2136 a C++ program. The new-style casts (@samp{dynamic_cast},
2137 @samp{static_cast}, @samp{reinterpret_cast}, and @samp{const_cast}) are
2138 less vulnerable to unintended effects and much easier to search for.
2140 @item -Woverloaded-virtual @r{(C++ and Objective-C++ only)}
2141 @opindex Woverloaded-virtual
2142 @opindex Wno-overloaded-virtual
2143 @cindex overloaded virtual fn, warning
2144 @cindex warning for overloaded virtual fn
2145 Warn when a function declaration hides virtual functions from a
2146 base class. For example, in:
2153 struct B: public A @{
2158 the @code{A} class version of @code{f} is hidden in @code{B}, and code
2166 will fail to compile.
2168 @item -Wno-pmf-conversions @r{(C++ and Objective-C++ only)}
2169 @opindex Wno-pmf-conversions
2170 @opindex Wpmf-conversions
2171 Disable the diagnostic for converting a bound pointer to member function
2174 @item -Wsign-promo @r{(C++ and Objective-C++ only)}
2175 @opindex Wsign-promo
2176 @opindex Wno-sign-promo
2177 Warn when overload resolution chooses a promotion from unsigned or
2178 enumerated type to a signed type, over a conversion to an unsigned type of
2179 the same size. Previous versions of G++ would try to preserve
2180 unsignedness, but the standard mandates the current behavior.
2185 A& operator = (int);
2195 In this example, G++ will synthesize a default @samp{A& operator =
2196 (const A&);}, while cfront will use the user-defined @samp{operator =}.
2199 @node Objective-C and Objective-C++ Dialect Options
2200 @section Options Controlling Objective-C and Objective-C++ Dialects
2202 @cindex compiler options, Objective-C and Objective-C++
2203 @cindex Objective-C and Objective-C++ options, command line
2204 @cindex options, Objective-C and Objective-C++
2205 (NOTE: This manual does not describe the Objective-C and Objective-C++
2206 languages themselves. See @xref{Standards,,Language Standards
2207 Supported by GCC}, for references.)
2209 This section describes the command-line options that are only meaningful
2210 for Objective-C and Objective-C++ programs, but you can also use most of
2211 the language-independent GNU compiler options.
2212 For example, you might compile a file @code{some_class.m} like this:
2215 gcc -g -fgnu-runtime -O -c some_class.m
2219 In this example, @option{-fgnu-runtime} is an option meant only for
2220 Objective-C and Objective-C++ programs; you can use the other options with
2221 any language supported by GCC@.
2223 Note that since Objective-C is an extension of the C language, Objective-C
2224 compilations may also use options specific to the C front-end (e.g.,
2225 @option{-Wtraditional}). Similarly, Objective-C++ compilations may use
2226 C++-specific options (e.g., @option{-Wabi}).
2228 Here is a list of options that are @emph{only} for compiling Objective-C
2229 and Objective-C++ programs:
2232 @item -fconstant-string-class=@var{class-name}
2233 @opindex fconstant-string-class
2234 Use @var{class-name} as the name of the class to instantiate for each
2235 literal string specified with the syntax @code{@@"@dots{}"}. The default
2236 class name is @code{NXConstantString} if the GNU runtime is being used, and
2237 @code{NSConstantString} if the NeXT runtime is being used (see below). The
2238 @option{-fconstant-cfstrings} option, if also present, will override the
2239 @option{-fconstant-string-class} setting and cause @code{@@"@dots{}"} literals
2240 to be laid out as constant CoreFoundation strings.
2243 @opindex fgnu-runtime
2244 Generate object code compatible with the standard GNU Objective-C
2245 runtime. This is the default for most types of systems.
2247 @item -fnext-runtime
2248 @opindex fnext-runtime
2249 Generate output compatible with the NeXT runtime. This is the default
2250 for NeXT-based systems, including Darwin and Mac OS X@. The macro
2251 @code{__NEXT_RUNTIME__} is predefined if (and only if) this option is
2254 @item -fno-nil-receivers
2255 @opindex fno-nil-receivers
2256 Assume that all Objective-C message dispatches (e.g.,
2257 @code{[receiver message:arg]}) in this translation unit ensure that the receiver
2258 is not @code{nil}. This allows for more efficient entry points in the runtime
2259 to be used. Currently, this option is only available in conjunction with
2260 the NeXT runtime on Mac OS X 10.3 and later.
2262 @item -fobjc-call-cxx-cdtors
2263 @opindex fobjc-call-cxx-cdtors
2264 For each Objective-C class, check if any of its instance variables is a
2265 C++ object with a non-trivial default constructor. If so, synthesize a
2266 special @code{- (id) .cxx_construct} instance method that will run
2267 non-trivial default constructors on any such instance variables, in order,
2268 and then return @code{self}. Similarly, check if any instance variable
2269 is a C++ object with a non-trivial destructor, and if so, synthesize a
2270 special @code{- (void) .cxx_destruct} method that will run
2271 all such default destructors, in reverse order.
2273 The @code{- (id) .cxx_construct} and/or @code{- (void) .cxx_destruct} methods
2274 thusly generated will only operate on instance variables declared in the
2275 current Objective-C class, and not those inherited from superclasses. It
2276 is the responsibility of the Objective-C runtime to invoke all such methods
2277 in an object's inheritance hierarchy. The @code{- (id) .cxx_construct} methods
2278 will be invoked by the runtime immediately after a new object
2279 instance is allocated; the @code{- (void) .cxx_destruct} methods will
2280 be invoked immediately before the runtime deallocates an object instance.
2282 As of this writing, only the NeXT runtime on Mac OS X 10.4 and later has
2283 support for invoking the @code{- (id) .cxx_construct} and
2284 @code{- (void) .cxx_destruct} methods.
2286 @item -fobjc-direct-dispatch
2287 @opindex fobjc-direct-dispatch
2288 Allow fast jumps to the message dispatcher. On Darwin this is
2289 accomplished via the comm page.
2291 @item -fobjc-exceptions
2292 @opindex fobjc-exceptions
2293 Enable syntactic support for structured exception handling in Objective-C,
2294 similar to what is offered by C++ and Java. This option is
2295 unavailable in conjunction with the NeXT runtime on Mac OS X 10.2 and
2304 @@catch (AnObjCClass *exc) @{
2311 @@catch (AnotherClass *exc) @{
2314 @@catch (id allOthers) @{
2324 The @code{@@throw} statement may appear anywhere in an Objective-C or
2325 Objective-C++ program; when used inside of a @code{@@catch} block, the
2326 @code{@@throw} may appear without an argument (as shown above), in which case
2327 the object caught by the @code{@@catch} will be rethrown.
2329 Note that only (pointers to) Objective-C objects may be thrown and
2330 caught using this scheme. When an object is thrown, it will be caught
2331 by the nearest @code{@@catch} clause capable of handling objects of that type,
2332 analogously to how @code{catch} blocks work in C++ and Java. A
2333 @code{@@catch(id @dots{})} clause (as shown above) may also be provided to catch
2334 any and all Objective-C exceptions not caught by previous @code{@@catch}
2337 The @code{@@finally} clause, if present, will be executed upon exit from the
2338 immediately preceding @code{@@try @dots{} @@catch} section. This will happen
2339 regardless of whether any exceptions are thrown, caught or rethrown
2340 inside the @code{@@try @dots{} @@catch} section, analogously to the behavior
2341 of the @code{finally} clause in Java.
2343 There are several caveats to using the new exception mechanism:
2347 Although currently designed to be binary compatible with @code{NS_HANDLER}-style
2348 idioms provided by the @code{NSException} class, the new
2349 exceptions can only be used on Mac OS X 10.3 (Panther) and later
2350 systems, due to additional functionality needed in the (NeXT) Objective-C
2354 As mentioned above, the new exceptions do not support handling
2355 types other than Objective-C objects. Furthermore, when used from
2356 Objective-C++, the Objective-C exception model does not interoperate with C++
2357 exceptions at this time. This means you cannot @code{@@throw} an exception
2358 from Objective-C and @code{catch} it in C++, or vice versa
2359 (i.e., @code{throw @dots{} @@catch}).
2362 The @option{-fobjc-exceptions} switch also enables the use of synchronization
2363 blocks for thread-safe execution:
2366 @@synchronized (ObjCClass *guard) @{
2371 Upon entering the @code{@@synchronized} block, a thread of execution shall
2372 first check whether a lock has been placed on the corresponding @code{guard}
2373 object by another thread. If it has, the current thread shall wait until
2374 the other thread relinquishes its lock. Once @code{guard} becomes available,
2375 the current thread will place its own lock on it, execute the code contained in
2376 the @code{@@synchronized} block, and finally relinquish the lock (thereby
2377 making @code{guard} available to other threads).
2379 Unlike Java, Objective-C does not allow for entire methods to be marked
2380 @code{@@synchronized}. Note that throwing exceptions out of
2381 @code{@@synchronized} blocks is allowed, and will cause the guarding object
2382 to be unlocked properly.
2386 Enable garbage collection (GC) in Objective-C and Objective-C++ programs.
2388 @item -freplace-objc-classes
2389 @opindex freplace-objc-classes
2390 Emit a special marker instructing @command{ld(1)} not to statically link in
2391 the resulting object file, and allow @command{dyld(1)} to load it in at
2392 run time instead. This is used in conjunction with the Fix-and-Continue
2393 debugging mode, where the object file in question may be recompiled and
2394 dynamically reloaded in the course of program execution, without the need
2395 to restart the program itself. Currently, Fix-and-Continue functionality
2396 is only available in conjunction with the NeXT runtime on Mac OS X 10.3
2401 When compiling for the NeXT runtime, the compiler ordinarily replaces calls
2402 to @code{objc_getClass("@dots{}")} (when the name of the class is known at
2403 compile time) with static class references that get initialized at load time,
2404 which improves run-time performance. Specifying the @option{-fzero-link} flag
2405 suppresses this behavior and causes calls to @code{objc_getClass("@dots{}")}
2406 to be retained. This is useful in Zero-Link debugging mode, since it allows
2407 for individual class implementations to be modified during program execution.
2411 Dump interface declarations for all classes seen in the source file to a
2412 file named @file{@var{sourcename}.decl}.
2414 @item -Wassign-intercept @r{(Objective-C and Objective-C++ only)}
2415 @opindex Wassign-intercept
2416 @opindex Wno-assign-intercept
2417 Warn whenever an Objective-C assignment is being intercepted by the
2420 @item -Wno-protocol @r{(Objective-C and Objective-C++ only)}
2421 @opindex Wno-protocol
2423 If a class is declared to implement a protocol, a warning is issued for
2424 every method in the protocol that is not implemented by the class. The
2425 default behavior is to issue a warning for every method not explicitly
2426 implemented in the class, even if a method implementation is inherited
2427 from the superclass. If you use the @option{-Wno-protocol} option, then
2428 methods inherited from the superclass are considered to be implemented,
2429 and no warning is issued for them.
2431 @item -Wselector @r{(Objective-C and Objective-C++ only)}
2433 @opindex Wno-selector
2434 Warn if multiple methods of different types for the same selector are
2435 found during compilation. The check is performed on the list of methods
2436 in the final stage of compilation. Additionally, a check is performed
2437 for each selector appearing in a @code{@@selector(@dots{})}
2438 expression, and a corresponding method for that selector has been found
2439 during compilation. Because these checks scan the method table only at
2440 the end of compilation, these warnings are not produced if the final
2441 stage of compilation is not reached, for example because an error is
2442 found during compilation, or because the @option{-fsyntax-only} option is
2445 @item -Wstrict-selector-match @r{(Objective-C and Objective-C++ only)}
2446 @opindex Wstrict-selector-match
2447 @opindex Wno-strict-selector-match
2448 Warn if multiple methods with differing argument and/or return types are
2449 found for a given selector when attempting to send a message using this
2450 selector to a receiver of type @code{id} or @code{Class}. When this flag
2451 is off (which is the default behavior), the compiler will omit such warnings
2452 if any differences found are confined to types which share the same size
2455 @item -Wundeclared-selector @r{(Objective-C and Objective-C++ only)}
2456 @opindex Wundeclared-selector
2457 @opindex Wno-undeclared-selector
2458 Warn if a @code{@@selector(@dots{})} expression referring to an
2459 undeclared selector is found. A selector is considered undeclared if no
2460 method with that name has been declared before the
2461 @code{@@selector(@dots{})} expression, either explicitly in an
2462 @code{@@interface} or @code{@@protocol} declaration, or implicitly in
2463 an @code{@@implementation} section. This option always performs its
2464 checks as soon as a @code{@@selector(@dots{})} expression is found,
2465 while @option{-Wselector} only performs its checks in the final stage of
2466 compilation. This also enforces the coding style convention
2467 that methods and selectors must be declared before being used.
2469 @item -print-objc-runtime-info
2470 @opindex print-objc-runtime-info
2471 Generate C header describing the largest structure that is passed by
2476 @node Language Independent Options
2477 @section Options to Control Diagnostic Messages Formatting
2478 @cindex options to control diagnostics formatting
2479 @cindex diagnostic messages
2480 @cindex message formatting
2482 Traditionally, diagnostic messages have been formatted irrespective of
2483 the output device's aspect (e.g.@: its width, @dots{}). The options described
2484 below can be used to control the diagnostic messages formatting
2485 algorithm, e.g.@: how many characters per line, how often source location
2486 information should be reported. Right now, only the C++ front end can
2487 honor these options. However it is expected, in the near future, that
2488 the remaining front ends would be able to digest them correctly.
2491 @item -fmessage-length=@var{n}
2492 @opindex fmessage-length
2493 Try to format error messages so that they fit on lines of about @var{n}
2494 characters. The default is 72 characters for @command{g++} and 0 for the rest of
2495 the front ends supported by GCC@. If @var{n} is zero, then no
2496 line-wrapping will be done; each error message will appear on a single
2499 @opindex fdiagnostics-show-location
2500 @item -fdiagnostics-show-location=once
2501 Only meaningful in line-wrapping mode. Instructs the diagnostic messages
2502 reporter to emit @emph{once} source location information; that is, in
2503 case the message is too long to fit on a single physical line and has to
2504 be wrapped, the source location won't be emitted (as prefix) again,
2505 over and over, in subsequent continuation lines. This is the default
2508 @item -fdiagnostics-show-location=every-line
2509 Only meaningful in line-wrapping mode. Instructs the diagnostic
2510 messages reporter to emit the same source location information (as
2511 prefix) for physical lines that result from the process of breaking
2512 a message which is too long to fit on a single line.
2514 @item -fdiagnostics-show-option
2515 @opindex fdiagnostics-show-option
2516 This option instructs the diagnostic machinery to add text to each
2517 diagnostic emitted, which indicates which command line option directly
2518 controls that diagnostic, when such an option is known to the
2519 diagnostic machinery.
2521 @item -Wcoverage-mismatch
2522 @opindex Wcoverage-mismatch
2523 Warn if feedback profiles do not match when using the
2524 @option{-fprofile-use} option.
2525 If a source file was changed between @option{-fprofile-gen} and
2526 @option{-fprofile-use}, the files with the profile feedback can fail
2527 to match the source file and GCC can not use the profile feedback
2528 information. By default, GCC emits an error message in this case.
2529 The option @option{-Wcoverage-mismatch} emits a warning instead of an
2530 error. GCC does not use appropriate feedback profiles, so using this
2531 option can result in poorly optimized code. This option is useful
2532 only in the case of very minor changes such as bug fixes to an
2537 @node Warning Options
2538 @section Options to Request or Suppress Warnings
2539 @cindex options to control warnings
2540 @cindex warning messages
2541 @cindex messages, warning
2542 @cindex suppressing warnings
2544 Warnings are diagnostic messages that report constructions which
2545 are not inherently erroneous but which are risky or suggest there
2546 may have been an error.
2548 The following language-independent options do not enable specific
2549 warnings but control the kinds of diagnostics produced by GCC.
2552 @cindex syntax checking
2554 @opindex fsyntax-only
2555 Check the code for syntax errors, but don't do anything beyond that.
2559 Inhibit all warning messages.
2564 Make all warnings into errors.
2569 Make the specified warning into an error. The specifier for a warning
2570 is appended, for example @option{-Werror=switch} turns the warnings
2571 controlled by @option{-Wswitch} into errors. This switch takes a
2572 negative form, to be used to negate @option{-Werror} for specific
2573 warnings, for example @option{-Wno-error=switch} makes
2574 @option{-Wswitch} warnings not be errors, even when @option{-Werror}
2575 is in effect. You can use the @option{-fdiagnostics-show-option}
2576 option to have each controllable warning amended with the option which
2577 controls it, to determine what to use with this option.
2579 Note that specifying @option{-Werror=}@var{foo} automatically implies
2580 @option{-W}@var{foo}. However, @option{-Wno-error=}@var{foo} does not
2583 @item -Wfatal-errors
2584 @opindex Wfatal-errors
2585 @opindex Wno-fatal-errors
2586 This option causes the compiler to abort compilation on the first error
2587 occurred rather than trying to keep going and printing further error
2592 You can request many specific warnings with options beginning
2593 @samp{-W}, for example @option{-Wimplicit} to request warnings on
2594 implicit declarations. Each of these specific warning options also
2595 has a negative form beginning @samp{-Wno-} to turn off warnings; for
2596 example, @option{-Wno-implicit}. This manual lists only one of the
2597 two forms, whichever is not the default. For further,
2598 language-specific options also refer to @ref{C++ Dialect Options} and
2599 @ref{Objective-C and Objective-C++ Dialect Options}.
2604 Issue all the warnings demanded by strict ISO C and ISO C++;
2605 reject all programs that use forbidden extensions, and some other
2606 programs that do not follow ISO C and ISO C++. For ISO C, follows the
2607 version of the ISO C standard specified by any @option{-std} option used.
2609 Valid ISO C and ISO C++ programs should compile properly with or without
2610 this option (though a rare few will require @option{-ansi} or a
2611 @option{-std} option specifying the required version of ISO C)@. However,
2612 without this option, certain GNU extensions and traditional C and C++
2613 features are supported as well. With this option, they are rejected.
2615 @option{-pedantic} does not cause warning messages for use of the
2616 alternate keywords whose names begin and end with @samp{__}. Pedantic
2617 warnings are also disabled in the expression that follows
2618 @code{__extension__}. However, only system header files should use
2619 these escape routes; application programs should avoid them.
2620 @xref{Alternate Keywords}.
2622 Some users try to use @option{-pedantic} to check programs for strict ISO
2623 C conformance. They soon find that it does not do quite what they want:
2624 it finds some non-ISO practices, but not all---only those for which
2625 ISO C @emph{requires} a diagnostic, and some others for which
2626 diagnostics have been added.
2628 A feature to report any failure to conform to ISO C might be useful in
2629 some instances, but would require considerable additional work and would
2630 be quite different from @option{-pedantic}. We don't have plans to
2631 support such a feature in the near future.
2633 Where the standard specified with @option{-std} represents a GNU
2634 extended dialect of C, such as @samp{gnu89} or @samp{gnu99}, there is a
2635 corresponding @dfn{base standard}, the version of ISO C on which the GNU
2636 extended dialect is based. Warnings from @option{-pedantic} are given
2637 where they are required by the base standard. (It would not make sense
2638 for such warnings to be given only for features not in the specified GNU
2639 C dialect, since by definition the GNU dialects of C include all
2640 features the compiler supports with the given option, and there would be
2641 nothing to warn about.)
2643 @item -pedantic-errors
2644 @opindex pedantic-errors
2645 Like @option{-pedantic}, except that errors are produced rather than
2651 This enables all the warnings about constructions that some users
2652 consider questionable, and that are easy to avoid (or modify to
2653 prevent the warning), even in conjunction with macros. This also
2654 enables some language-specific warnings described in @ref{C++ Dialect
2655 Options} and @ref{Objective-C and Objective-C++ Dialect Options}.
2657 @option{-Wall} turns on the following warning flags:
2659 @gccoptlist{-Waddress @gol
2660 -Warray-bounds @r{(only with} @option{-O2}@r{)} @gol
2662 -Wchar-subscripts @gol
2664 -Wimplicit-function-declaration @gol
2667 -Wmain @r{(only for C/ObjC and unless} @option{-ffreestanding}@r{)} @gol
2668 -Wmissing-braces @gol
2674 -Wsequence-point @gol
2675 -Wsign-compare @r{(only in C++)} @gol
2676 -Wstrict-aliasing @gol
2677 -Wstrict-overflow=1 @gol
2680 -Wuninitialized @r{(only with} @option{-O1} @r{and above)} @gol
2681 -Wunknown-pragmas @gol
2682 -Wunused-function @gol
2685 -Wunused-variable @gol
2686 -Wvolatile-register-var @gol
2689 Note that some warning flags are not implied by @option{-Wall}. Some of
2690 them warn about constructions that users generally do not consider
2691 questionable, but which occasionally you might wish to check for;
2692 others warn about constructions that are necessary or hard to avoid in
2693 some cases, and there is no simple way to modify the code to suppress
2694 the warning. Some of them are enabled by @option{-Wextra} but many of
2695 them must be enabled individually.
2701 This enables some extra warning flags that are not enabled by
2702 @option{-Wall}. (This option used to be called @option{-W}. The older
2703 name is still supported, but the newer name is more descriptive.)
2705 @gccoptlist{-Wclobbered @gol
2707 -Wignored-qualifiers @gol
2708 -Wmissing-field-initializers @gol
2709 -Wmissing-parameter-type @r{(C only)} @gol
2710 -Wold-style-declaration @r{(C only)} @gol
2711 -Woverride-init @gol
2714 -Wuninitialized @r{(only with} @option{-O1} @r{and above)} @gol
2715 -Wunused-parameter @r{(only with} @option{-Wunused} @r{or} @option{-Wall}@r{)} @gol
2718 The option @option{-Wextra} also prints warning messages for the
2724 A pointer is compared against integer zero with @samp{<}, @samp{<=},
2725 @samp{>}, or @samp{>=}.
2728 (C++ only) An enumerator and a non-enumerator both appear in a
2729 conditional expression.
2732 (C++ only) A non-static reference or non-static @samp{const} member
2733 appears in a class without constructors.
2736 (C++ only) Ambiguous virtual bases.
2739 (C++ only) Subscripting an array which has been declared @samp{register}.
2742 (C++ only) Taking the address of a variable which has been declared
2746 (C++ only) A base class is not initialized in a derived class' copy
2754 Inhibit warning messages about the use of @samp{#import}.
2756 @item -Wchar-subscripts
2757 @opindex Wchar-subscripts
2758 @opindex Wno-char-subscripts
2759 Warn if an array subscript has type @code{char}. This is a common cause
2760 of error, as programmers often forget that this type is signed on some
2762 This warning is enabled by @option{-Wall}.
2766 @opindex Wno-comment
2767 Warn whenever a comment-start sequence @samp{/*} appears in a @samp{/*}
2768 comment, or whenever a Backslash-Newline appears in a @samp{//} comment.
2769 This warning is enabled by @option{-Wall}.
2774 @opindex ffreestanding
2775 @opindex fno-builtin
2776 Check calls to @code{printf} and @code{scanf}, etc., to make sure that
2777 the arguments supplied have types appropriate to the format string
2778 specified, and that the conversions specified in the format string make
2779 sense. This includes standard functions, and others specified by format
2780 attributes (@pxref{Function Attributes}), in the @code{printf},
2781 @code{scanf}, @code{strftime} and @code{strfmon} (an X/Open extension,
2782 not in the C standard) families (or other target-specific families).
2783 Which functions are checked without format attributes having been
2784 specified depends on the standard version selected, and such checks of
2785 functions without the attribute specified are disabled by
2786 @option{-ffreestanding} or @option{-fno-builtin}.
2788 The formats are checked against the format features supported by GNU
2789 libc version 2.2. These include all ISO C90 and C99 features, as well
2790 as features from the Single Unix Specification and some BSD and GNU
2791 extensions. Other library implementations may not support all these
2792 features; GCC does not support warning about features that go beyond a
2793 particular library's limitations. However, if @option{-pedantic} is used
2794 with @option{-Wformat}, warnings will be given about format features not
2795 in the selected standard version (but not for @code{strfmon} formats,
2796 since those are not in any version of the C standard). @xref{C Dialect
2797 Options,,Options Controlling C Dialect}.
2799 Since @option{-Wformat} also checks for null format arguments for
2800 several functions, @option{-Wformat} also implies @option{-Wnonnull}.
2802 @option{-Wformat} is included in @option{-Wall}. For more control over some
2803 aspects of format checking, the options @option{-Wformat-y2k},
2804 @option{-Wno-format-extra-args}, @option{-Wno-format-zero-length},
2805 @option{-Wformat-nonliteral}, @option{-Wformat-security}, and
2806 @option{-Wformat=2} are available, but are not included in @option{-Wall}.
2809 @opindex Wformat-y2k
2810 @opindex Wno-format-y2k
2811 If @option{-Wformat} is specified, also warn about @code{strftime}
2812 formats which may yield only a two-digit year.
2814 @item -Wno-format-contains-nul
2815 @opindex Wno-format-contains-nul
2816 @opindex Wformat-contains-nul
2817 If @option{-Wformat} is specified, do not warn about format strings that
2820 @item -Wno-format-extra-args
2821 @opindex Wno-format-extra-args
2822 @opindex Wformat-extra-args
2823 If @option{-Wformat} is specified, do not warn about excess arguments to a
2824 @code{printf} or @code{scanf} format function. The C standard specifies
2825 that such arguments are ignored.
2827 Where the unused arguments lie between used arguments that are
2828 specified with @samp{$} operand number specifications, normally
2829 warnings are still given, since the implementation could not know what
2830 type to pass to @code{va_arg} to skip the unused arguments. However,
2831 in the case of @code{scanf} formats, this option will suppress the
2832 warning if the unused arguments are all pointers, since the Single
2833 Unix Specification says that such unused arguments are allowed.
2835 @item -Wno-format-zero-length @r{(C and Objective-C only)}
2836 @opindex Wno-format-zero-length
2837 @opindex Wformat-zero-length
2838 If @option{-Wformat} is specified, do not warn about zero-length formats.
2839 The C standard specifies that zero-length formats are allowed.
2841 @item -Wformat-nonliteral
2842 @opindex Wformat-nonliteral
2843 @opindex Wno-format-nonliteral
2844 If @option{-Wformat} is specified, also warn if the format string is not a
2845 string literal and so cannot be checked, unless the format function
2846 takes its format arguments as a @code{va_list}.
2848 @item -Wformat-security
2849 @opindex Wformat-security
2850 @opindex Wno-format-security
2851 If @option{-Wformat} is specified, also warn about uses of format
2852 functions that represent possible security problems. At present, this
2853 warns about calls to @code{printf} and @code{scanf} functions where the
2854 format string is not a string literal and there are no format arguments,
2855 as in @code{printf (foo);}. This may be a security hole if the format
2856 string came from untrusted input and contains @samp{%n}. (This is
2857 currently a subset of what @option{-Wformat-nonliteral} warns about, but
2858 in future warnings may be added to @option{-Wformat-security} that are not
2859 included in @option{-Wformat-nonliteral}.)
2863 @opindex Wno-format=2
2864 Enable @option{-Wformat} plus format checks not included in
2865 @option{-Wformat}. Currently equivalent to @samp{-Wformat
2866 -Wformat-nonliteral -Wformat-security -Wformat-y2k}.
2868 @item -Wnonnull @r{(C and Objective-C only)}
2870 @opindex Wno-nonnull
2871 Warn about passing a null pointer for arguments marked as
2872 requiring a non-null value by the @code{nonnull} function attribute.
2874 @option{-Wnonnull} is included in @option{-Wall} and @option{-Wformat}. It
2875 can be disabled with the @option{-Wno-nonnull} option.
2877 @item -Winit-self @r{(C, C++, Objective-C and Objective-C++ only)}
2879 @opindex Wno-init-self
2880 Warn about uninitialized variables which are initialized with themselves.
2881 Note this option can only be used with the @option{-Wuninitialized} option,
2882 which in turn only works with @option{-O1} and above.
2884 For example, GCC will warn about @code{i} being uninitialized in the
2885 following snippet only when @option{-Winit-self} has been specified:
2896 @item -Wimplicit-int @r{(C and Objective-C only)}
2897 @opindex Wimplicit-int
2898 @opindex Wno-implicit-int
2899 Warn when a declaration does not specify a type.
2900 This warning is enabled by @option{-Wall}.
2902 @item -Wimplicit-function-declaration @r{(C and Objective-C only)}
2903 @opindex Wimplicit-function-declaration
2904 @opindex Wno-implicit-function-declaration
2905 Give a warning whenever a function is used before being declared. In
2906 C99 mode (@option{-std=c99} or @option{-std=gnu99}), this warning is
2907 enabled by default and it is made into an error by
2908 @option{-pedantic-errors}. This warning is also enabled by
2913 @opindex Wno-implicit
2914 Same as @option{-Wimplicit-int} and @option{-Wimplicit-function-declaration}.
2915 This warning is enabled by @option{-Wall}.
2917 @item -Wignored-qualifiers @r{(C and C++ only)}
2918 @opindex Wignored-qualifiers
2919 @opindex Wno-ignored-qualifiers
2920 Warn if the return type of a function has a type qualifier
2921 such as @code{const}. For ISO C such a type qualifier has no effect,
2922 since the value returned by a function is not an lvalue.
2923 For C++, the warning is only emitted for scalar types or @code{void}.
2924 ISO C prohibits qualified @code{void} return types on function
2925 definitions, so such return types always receive a warning
2926 even without this option.
2928 This warning is also enabled by @option{-Wextra}.
2933 Warn if the type of @samp{main} is suspicious. @samp{main} should be a
2934 function with external linkage, returning int, taking either zero
2935 arguments, two, or three arguments of appropriate types.
2936 This warning is enabled by @option{-Wall}.
2938 @item -Wmissing-braces
2939 @opindex Wmissing-braces
2940 @opindex Wno-missing-braces
2941 Warn if an aggregate or union initializer is not fully bracketed. In
2942 the following example, the initializer for @samp{a} is not fully
2943 bracketed, but that for @samp{b} is fully bracketed.
2946 int a[2][2] = @{ 0, 1, 2, 3 @};
2947 int b[2][2] = @{ @{ 0, 1 @}, @{ 2, 3 @} @};
2950 This warning is enabled by @option{-Wall}.
2952 @item -Wmissing-include-dirs @r{(C, C++, Objective-C and Objective-C++ only)}
2953 @opindex Wmissing-include-dirs
2954 @opindex Wno-missing-include-dirs
2955 Warn if a user-supplied include directory does not exist.
2958 @opindex Wparentheses
2959 @opindex Wno-parentheses
2960 Warn if parentheses are omitted in certain contexts, such
2961 as when there is an assignment in a context where a truth value
2962 is expected, or when operators are nested whose precedence people
2963 often get confused about.
2965 Also warn if a comparison like @samp{x<=y<=z} appears; this is
2966 equivalent to @samp{(x<=y ? 1 : 0) <= z}, which is a different
2967 interpretation from that of ordinary mathematical notation.
2969 Also warn about constructions where there may be confusion to which
2970 @code{if} statement an @code{else} branch belongs. Here is an example of
2985 In C/C++, every @code{else} branch belongs to the innermost possible
2986 @code{if} statement, which in this example is @code{if (b)}. This is
2987 often not what the programmer expected, as illustrated in the above
2988 example by indentation the programmer chose. When there is the
2989 potential for this confusion, GCC will issue a warning when this flag
2990 is specified. To eliminate the warning, add explicit braces around
2991 the innermost @code{if} statement so there is no way the @code{else}
2992 could belong to the enclosing @code{if}. The resulting code would
3009 This warning is enabled by @option{-Wall}.
3011 @item -Wsequence-point
3012 @opindex Wsequence-point
3013 @opindex Wno-sequence-point
3014 Warn about code that may have undefined semantics because of violations
3015 of sequence point rules in the C and C++ standards.
3017 The C and C++ standards defines the order in which expressions in a C/C++
3018 program are evaluated in terms of @dfn{sequence points}, which represent
3019 a partial ordering between the execution of parts of the program: those
3020 executed before the sequence point, and those executed after it. These
3021 occur after the evaluation of a full expression (one which is not part
3022 of a larger expression), after the evaluation of the first operand of a
3023 @code{&&}, @code{||}, @code{? :} or @code{,} (comma) operator, before a
3024 function is called (but after the evaluation of its arguments and the
3025 expression denoting the called function), and in certain other places.
3026 Other than as expressed by the sequence point rules, the order of
3027 evaluation of subexpressions of an expression is not specified. All
3028 these rules describe only a partial order rather than a total order,
3029 since, for example, if two functions are called within one expression
3030 with no sequence point between them, the order in which the functions
3031 are called is not specified. However, the standards committee have
3032 ruled that function calls do not overlap.
3034 It is not specified when between sequence points modifications to the
3035 values of objects take effect. Programs whose behavior depends on this
3036 have undefined behavior; the C and C++ standards specify that ``Between
3037 the previous and next sequence point an object shall have its stored
3038 value modified at most once by the evaluation of an expression.
3039 Furthermore, the prior value shall be read only to determine the value
3040 to be stored.''. If a program breaks these rules, the results on any
3041 particular implementation are entirely unpredictable.
3043 Examples of code with undefined behavior are @code{a = a++;}, @code{a[n]
3044 = b[n++]} and @code{a[i++] = i;}. Some more complicated cases are not
3045 diagnosed by this option, and it may give an occasional false positive
3046 result, but in general it has been found fairly effective at detecting
3047 this sort of problem in programs.
3049 The standard is worded confusingly, therefore there is some debate
3050 over the precise meaning of the sequence point rules in subtle cases.
3051 Links to discussions of the problem, including proposed formal
3052 definitions, may be found on the GCC readings page, at
3053 @w{@uref{http://gcc.gnu.org/readings.html}}.
3055 This warning is enabled by @option{-Wall} for C and C++.
3058 @opindex Wreturn-type
3059 @opindex Wno-return-type
3060 Warn whenever a function is defined with a return-type that defaults
3061 to @code{int}. Also warn about any @code{return} statement with no
3062 return-value in a function whose return-type is not @code{void}
3063 (falling off the end of the function body is considered returning
3064 without a value), and about a @code{return} statement with a
3065 expression in a function whose return-type is @code{void}.
3067 For C++, a function without return type always produces a diagnostic
3068 message, even when @option{-Wno-return-type} is specified. The only
3069 exceptions are @samp{main} and functions defined in system headers.
3071 This warning is enabled by @option{-Wall}.
3076 Warn whenever a @code{switch} statement has an index of enumerated type
3077 and lacks a @code{case} for one or more of the named codes of that
3078 enumeration. (The presence of a @code{default} label prevents this
3079 warning.) @code{case} labels outside the enumeration range also
3080 provoke warnings when this option is used.
3081 This warning is enabled by @option{-Wall}.
3083 @item -Wswitch-default
3084 @opindex Wswitch-default
3085 @opindex Wno-switch-default
3086 Warn whenever a @code{switch} statement does not have a @code{default}
3090 @opindex Wswitch-enum
3091 @opindex Wno-switch-enum
3092 Warn whenever a @code{switch} statement has an index of enumerated type
3093 and lacks a @code{case} for one or more of the named codes of that
3094 enumeration. @code{case} labels outside the enumeration range also
3095 provoke warnings when this option is used.
3099 @opindex Wno-trigraphs
3100 Warn if any trigraphs are encountered that might change the meaning of
3101 the program (trigraphs within comments are not warned about).
3102 This warning is enabled by @option{-Wall}.
3104 @item -Wunused-function
3105 @opindex Wunused-function
3106 @opindex Wno-unused-function
3107 Warn whenever a static function is declared but not defined or a
3108 non-inline static function is unused.
3109 This warning is enabled by @option{-Wall}.
3111 @item -Wunused-label
3112 @opindex Wunused-label
3113 @opindex Wno-unused-label
3114 Warn whenever a label is declared but not used.
3115 This warning is enabled by @option{-Wall}.
3117 To suppress this warning use the @samp{unused} attribute
3118 (@pxref{Variable Attributes}).
3120 @item -Wunused-parameter
3121 @opindex Wunused-parameter
3122 @opindex Wno-unused-parameter
3123 Warn whenever a function parameter is unused aside from its declaration.
3125 To suppress this warning use the @samp{unused} attribute
3126 (@pxref{Variable Attributes}).
3128 @item -Wunused-variable
3129 @opindex Wunused-variable
3130 @opindex Wno-unused-variable
3131 Warn whenever a local variable or non-constant static variable is unused
3132 aside from its declaration.
3133 This warning is enabled by @option{-Wall}.
3135 To suppress this warning use the @samp{unused} attribute
3136 (@pxref{Variable Attributes}).
3138 @item -Wunused-value
3139 @opindex Wunused-value
3140 @opindex Wno-unused-value
3141 Warn whenever a statement computes a result that is explicitly not
3142 used. To suppress this warning cast the unused expression to
3143 @samp{void}. This includes an expression-statement or the left-hand
3144 side of a comma expression that contains no side effects. For example,
3145 an expression such as @samp{x[i,j]} will cause a warning, while
3146 @samp{x[(void)i,j]} will not.
3148 This warning is enabled by @option{-Wall}.
3153 All the above @option{-Wunused} options combined.
3155 In order to get a warning about an unused function parameter, you must
3156 either specify @samp{-Wextra -Wunused} (note that @samp{-Wall} implies
3157 @samp{-Wunused}), or separately specify @option{-Wunused-parameter}.
3159 @item -Wuninitialized
3160 @opindex Wuninitialized
3161 @opindex Wno-uninitialized
3162 Warn if an automatic variable is used without first being initialized or
3163 if a variable may be clobbered by a @code{setjmp} call.
3165 These warnings are possible only in optimizing compilation,
3166 because they require data flow information that is computed only
3167 when optimizing. If you do not specify @option{-O}, you will not get
3168 these warnings. Instead, GCC will issue a warning about @option{-Wuninitialized}
3169 requiring @option{-O}.
3171 If you want to warn about code which uses the uninitialized value of the
3172 variable in its own initializer, use the @option{-Winit-self} option.
3174 These warnings occur for individual uninitialized or clobbered
3175 elements of structure, union or array variables as well as for
3176 variables which are uninitialized or clobbered as a whole. They do
3177 not occur for variables or elements declared @code{volatile}. Because
3178 these warnings depend on optimization, the exact variables or elements
3179 for which there are warnings will depend on the precise optimization
3180 options and version of GCC used.
3182 Note that there may be no warning about a variable that is used only
3183 to compute a value that itself is never used, because such
3184 computations may be deleted by data flow analysis before the warnings
3187 These warnings are made optional because GCC is not smart
3188 enough to see all the reasons why the code might be correct
3189 despite appearing to have an error. Here is one example of how
3210 If the value of @code{y} is always 1, 2 or 3, then @code{x} is
3211 always initialized, but GCC doesn't know this. Here is
3212 another common case:
3217 if (change_y) save_y = y, y = new_y;
3219 if (change_y) y = save_y;
3224 This has no bug because @code{save_y} is used only if it is set.
3226 @cindex @code{longjmp} warnings
3227 This option also warns when a non-volatile automatic variable might be
3228 changed by a call to @code{longjmp}. These warnings as well are possible
3229 only in optimizing compilation.
3231 The compiler sees only the calls to @code{setjmp}. It cannot know
3232 where @code{longjmp} will be called; in fact, a signal handler could
3233 call it at any point in the code. As a result, you may get a warning
3234 even when there is in fact no problem because @code{longjmp} cannot
3235 in fact be called at the place which would cause a problem.
3237 Some spurious warnings can be avoided if you declare all the functions
3238 you use that never return as @code{noreturn}. @xref{Function
3241 This warning is enabled by @option{-Wall} or @option{-Wextra} in
3242 optimizing compilations (@option{-O1} and above).
3244 @item -Wunknown-pragmas
3245 @opindex Wunknown-pragmas
3246 @opindex Wno-unknown-pragmas
3247 @cindex warning for unknown pragmas
3248 @cindex unknown pragmas, warning
3249 @cindex pragmas, warning of unknown
3250 Warn when a #pragma directive is encountered which is not understood by
3251 GCC@. If this command line option is used, warnings will even be issued
3252 for unknown pragmas in system header files. This is not the case if
3253 the warnings were only enabled by the @option{-Wall} command line option.
3256 @opindex Wno-pragmas
3258 Do not warn about misuses of pragmas, such as incorrect parameters,
3259 invalid syntax, or conflicts between pragmas. See also
3260 @samp{-Wunknown-pragmas}.
3262 @item -Wstrict-aliasing
3263 @opindex Wstrict-aliasing
3264 @opindex Wno-strict-aliasing
3265 This option is only active when @option{-fstrict-aliasing} is active.
3266 It warns about code which might break the strict aliasing rules that the
3267 compiler is using for optimization. The warning does not catch all
3268 cases, but does attempt to catch the more common pitfalls. It is
3269 included in @option{-Wall}.
3270 It is equivalent to @option{-Wstrict-aliasing=3}
3272 @item -Wstrict-aliasing=n
3273 @opindex Wstrict-aliasing=n
3274 @opindex Wno-strict-aliasing=n
3275 This option is only active when @option{-fstrict-aliasing} is active.
3276 It warns about code which might break the strict aliasing rules that the
3277 compiler is using for optimization.
3278 Higher levels correspond to higher accuracy (fewer false positives).
3279 Higher levels also correspond to more effort, similar to the way -O works.
3280 @option{-Wstrict-aliasing} is equivalent to @option{-Wstrict-aliasing=n},
3283 Level 1: Most aggressive, quick, least accurate.
3284 Possibly useful when higher levels
3285 do not warn but -fstrict-aliasing still breaks the code, as it has very few
3286 false negatives. However, it has many false positives.
3287 Warns for all pointer conversions between possibly incompatible types,
3288 even if never dereferenced. Runs in the frontend only.
3290 Level 2: Aggressive, quick, not too precise.
3291 May still have many false positives (not as many as level 1 though),
3292 and few false negatives (but possibly more than level 1).
3293 Unlike level 1, it only warns when an address is taken. Warns about
3294 incomplete types. Runs in the frontend only.
3296 Level 3 (default for @option{-Wstrict-aliasing}):
3297 Should have very few false positives and few false
3298 negatives. Slightly slower than levels 1 or 2 when optimization is enabled.
3299 Takes care of the common punn+dereference pattern in the frontend:
3300 @code{*(int*)&some_float}.
3301 If optimization is enabled, it also runs in the backend, where it deals
3302 with multiple statement cases using flow-sensitive points-to information.
3303 Only warns when the converted pointer is dereferenced.
3304 Does not warn about incomplete types.
3306 @item -Wstrict-overflow
3307 @itemx -Wstrict-overflow=@var{n}
3308 @opindex Wstrict-overflow
3309 @opindex Wno-strict-overflow
3310 This option is only active when @option{-fstrict-overflow} is active.
3311 It warns about cases where the compiler optimizes based on the
3312 assumption that signed overflow does not occur. Note that it does not
3313 warn about all cases where the code might overflow: it only warns
3314 about cases where the compiler implements some optimization. Thus
3315 this warning depends on the optimization level.
3317 An optimization which assumes that signed overflow does not occur is
3318 perfectly safe if the values of the variables involved are such that
3319 overflow never does, in fact, occur. Therefore this warning can
3320 easily give a false positive: a warning about code which is not
3321 actually a problem. To help focus on important issues, several
3322 warning levels are defined. No warnings are issued for the use of
3323 undefined signed overflow when estimating how many iterations a loop
3324 will require, in particular when determining whether a loop will be
3328 @item -Wstrict-overflow=1
3329 Warn about cases which are both questionable and easy to avoid. For
3330 example: @code{x + 1 > x}; with @option{-fstrict-overflow}, the
3331 compiler will simplify this to @code{1}. This level of
3332 @option{-Wstrict-overflow} is enabled by @option{-Wall}; higher levels
3333 are not, and must be explicitly requested.
3335 @item -Wstrict-overflow=2
3336 Also warn about other cases where a comparison is simplified to a
3337 constant. For example: @code{abs (x) >= 0}. This can only be
3338 simplified when @option{-fstrict-overflow} is in effect, because
3339 @code{abs (INT_MIN)} overflows to @code{INT_MIN}, which is less than
3340 zero. @option{-Wstrict-overflow} (with no level) is the same as
3341 @option{-Wstrict-overflow=2}.
3343 @item -Wstrict-overflow=3
3344 Also warn about other cases where a comparison is simplified. For
3345 example: @code{x + 1 > 1} will be simplified to @code{x > 0}.
3347 @item -Wstrict-overflow=4
3348 Also warn about other simplifications not covered by the above cases.
3349 For example: @code{(x * 10) / 5} will be simplified to @code{x * 2}.
3351 @item -Wstrict-overflow=5
3352 Also warn about cases where the compiler reduces the magnitude of a
3353 constant involved in a comparison. For example: @code{x + 2 > y} will
3354 be simplified to @code{x + 1 >= y}. This is reported only at the
3355 highest warning level because this simplification applies to many
3356 comparisons, so this warning level will give a very large number of
3360 @item -Warray-bounds
3361 @opindex Wno-array-bounds
3362 @opindex Warray-bounds
3363 This option is only active when @option{-ftree-vrp} is active
3364 (default for -O2 and above). It warns about subscripts to arrays
3365 that are always out of bounds. This warning is enabled by @option{-Wall}.
3367 @item -Wno-div-by-zero
3368 @opindex Wno-div-by-zero
3369 @opindex Wdiv-by-zero
3370 Do not warn about compile-time integer division by zero. Floating point
3371 division by zero is not warned about, as it can be a legitimate way of
3372 obtaining infinities and NaNs.
3374 @item -Wsystem-headers
3375 @opindex Wsystem-headers
3376 @opindex Wno-system-headers
3377 @cindex warnings from system headers
3378 @cindex system headers, warnings from
3379 Print warning messages for constructs found in system header files.
3380 Warnings from system headers are normally suppressed, on the assumption
3381 that they usually do not indicate real problems and would only make the
3382 compiler output harder to read. Using this command line option tells
3383 GCC to emit warnings from system headers as if they occurred in user
3384 code. However, note that using @option{-Wall} in conjunction with this
3385 option will @emph{not} warn about unknown pragmas in system
3386 headers---for that, @option{-Wunknown-pragmas} must also be used.
3389 @opindex Wfloat-equal
3390 @opindex Wno-float-equal
3391 Warn if floating point values are used in equality comparisons.
3393 The idea behind this is that sometimes it is convenient (for the
3394 programmer) to consider floating-point values as approximations to
3395 infinitely precise real numbers. If you are doing this, then you need
3396 to compute (by analyzing the code, or in some other way) the maximum or
3397 likely maximum error that the computation introduces, and allow for it
3398 when performing comparisons (and when producing output, but that's a
3399 different problem). In particular, instead of testing for equality, you
3400 would check to see whether the two values have ranges that overlap; and
3401 this is done with the relational operators, so equality comparisons are
3404 @item -Wtraditional @r{(C and Objective-C only)}
3405 @opindex Wtraditional
3406 @opindex Wno-traditional
3407 Warn about certain constructs that behave differently in traditional and
3408 ISO C@. Also warn about ISO C constructs that have no traditional C
3409 equivalent, and/or problematic constructs which should be avoided.
3413 Macro parameters that appear within string literals in the macro body.
3414 In traditional C macro replacement takes place within string literals,
3415 but does not in ISO C@.
3418 In traditional C, some preprocessor directives did not exist.
3419 Traditional preprocessors would only consider a line to be a directive
3420 if the @samp{#} appeared in column 1 on the line. Therefore
3421 @option{-Wtraditional} warns about directives that traditional C
3422 understands but would ignore because the @samp{#} does not appear as the
3423 first character on the line. It also suggests you hide directives like
3424 @samp{#pragma} not understood by traditional C by indenting them. Some
3425 traditional implementations would not recognize @samp{#elif}, so it
3426 suggests avoiding it altogether.
3429 A function-like macro that appears without arguments.
3432 The unary plus operator.
3435 The @samp{U} integer constant suffix, or the @samp{F} or @samp{L} floating point
3436 constant suffixes. (Traditional C does support the @samp{L} suffix on integer
3437 constants.) Note, these suffixes appear in macros defined in the system
3438 headers of most modern systems, e.g.@: the @samp{_MIN}/@samp{_MAX} macros in @code{<limits.h>}.
3439 Use of these macros in user code might normally lead to spurious
3440 warnings, however GCC's integrated preprocessor has enough context to
3441 avoid warning in these cases.
3444 A function declared external in one block and then used after the end of
3448 A @code{switch} statement has an operand of type @code{long}.
3451 A non-@code{static} function declaration follows a @code{static} one.
3452 This construct is not accepted by some traditional C compilers.
3455 The ISO type of an integer constant has a different width or
3456 signedness from its traditional type. This warning is only issued if
3457 the base of the constant is ten. I.e.@: hexadecimal or octal values, which
3458 typically represent bit patterns, are not warned about.
3461 Usage of ISO string concatenation is detected.
3464 Initialization of automatic aggregates.
3467 Identifier conflicts with labels. Traditional C lacks a separate
3468 namespace for labels.
3471 Initialization of unions. If the initializer is zero, the warning is
3472 omitted. This is done under the assumption that the zero initializer in
3473 user code appears conditioned on e.g.@: @code{__STDC__} to avoid missing
3474 initializer warnings and relies on default initialization to zero in the
3478 Conversions by prototypes between fixed/floating point values and vice
3479 versa. The absence of these prototypes when compiling with traditional
3480 C would cause serious problems. This is a subset of the possible
3481 conversion warnings, for the full set use @option{-Wtraditional-conversion}.
3484 Use of ISO C style function definitions. This warning intentionally is
3485 @emph{not} issued for prototype declarations or variadic functions
3486 because these ISO C features will appear in your code when using
3487 libiberty's traditional C compatibility macros, @code{PARAMS} and
3488 @code{VPARAMS}. This warning is also bypassed for nested functions
3489 because that feature is already a GCC extension and thus not relevant to
3490 traditional C compatibility.
3493 @item -Wtraditional-conversion @r{(C and Objective-C only)}
3494 @opindex Wtraditional-conversion
3495 @opindex Wno-traditional-conversion
3496 Warn if a prototype causes a type conversion that is different from what
3497 would happen to the same argument in the absence of a prototype. This
3498 includes conversions of fixed point to floating and vice versa, and
3499 conversions changing the width or signedness of a fixed point argument
3500 except when the same as the default promotion.
3502 @item -Wdeclaration-after-statement @r{(C and Objective-C only)}
3503 @opindex Wdeclaration-after-statement
3504 @opindex Wno-declaration-after-statement
3505 Warn when a declaration is found after a statement in a block. This
3506 construct, known from C++, was introduced with ISO C99 and is by default
3507 allowed in GCC@. It is not supported by ISO C90 and was not supported by
3508 GCC versions before GCC 3.0. @xref{Mixed Declarations}.
3513 Warn if an undefined identifier is evaluated in an @samp{#if} directive.
3515 @item -Wno-endif-labels
3516 @opindex Wno-endif-labels
3517 @opindex Wendif-labels
3518 Do not warn whenever an @samp{#else} or an @samp{#endif} are followed by text.
3523 Warn whenever a local variable shadows another local variable, parameter or
3524 global variable or whenever a built-in function is shadowed.
3526 @item -Wlarger-than=@var{len}
3527 @opindex Wlarger-than=@var{len}
3528 @opindex Wlarger-than-@var{len}
3529 Warn whenever an object of larger than @var{len} bytes is defined.
3531 @item -Wframe-larger-than=@var{len}
3532 @opindex Wframe-larger-than
3533 Warn whenever the size of a function frame is larger than @var{len} bytes.
3535 @item -Wunsafe-loop-optimizations
3536 @opindex Wunsafe-loop-optimizations
3537 @opindex Wno-unsafe-loop-optimizations
3538 Warn if the loop cannot be optimized because the compiler could not
3539 assume anything on the bounds of the loop indices. With
3540 @option{-funsafe-loop-optimizations} warn if the compiler made
3543 @item -Wpointer-arith
3544 @opindex Wpointer-arith
3545 @opindex Wno-pointer-arith
3546 Warn about anything that depends on the ``size of'' a function type or
3547 of @code{void}. GNU C assigns these types a size of 1, for
3548 convenience in calculations with @code{void *} pointers and pointers
3549 to functions. In C++, warn also when an arithmetic operation involves
3550 @code{NULL}. This warning is also enabled by @option{-pedantic}.
3553 @opindex Wtype-limits
3554 @opindex Wno-type-limits
3555 Warn if a comparison is always true or always false due to the limited
3556 range of the data type, but do not warn for constant expressions. For
3557 example, warn if an unsigned variable is compared against zero with
3558 @samp{<} or @samp{>=}. This warning is also enabled by
3561 @item -Wbad-function-cast @r{(C and Objective-C only)}
3562 @opindex Wbad-function-cast
3563 @opindex Wno-bad-function-cast
3564 Warn whenever a function call is cast to a non-matching type.
3565 For example, warn if @code{int malloc()} is cast to @code{anything *}.
3567 @item -Wc++-compat @r{(C and Objective-C only)}
3568 Warn about ISO C constructs that are outside of the common subset of
3569 ISO C and ISO C++, e.g.@: request for implicit conversion from
3570 @code{void *} to a pointer to non-@code{void} type.
3572 @item -Wc++0x-compat @r{(C++ and Objective-C++ only)}
3573 Warn about C++ constructs whose meaning differs between ISO C++ 1998 and
3574 ISO C++ 200x, e.g., identifiers in ISO C++ 1998 that will become keywords
3575 in ISO C++ 200x. This warning is enabled by @option{-Wall}.
3579 @opindex Wno-cast-qual
3580 Warn whenever a pointer is cast so as to remove a type qualifier from
3581 the target type. For example, warn if a @code{const char *} is cast
3582 to an ordinary @code{char *}.
3585 @opindex Wcast-align
3586 @opindex Wno-cast-align
3587 Warn whenever a pointer is cast such that the required alignment of the
3588 target is increased. For example, warn if a @code{char *} is cast to
3589 an @code{int *} on machines where integers can only be accessed at
3590 two- or four-byte boundaries.
3592 @item -Wwrite-strings
3593 @opindex Wwrite-strings
3594 @opindex Wno-write-strings
3595 When compiling C, give string constants the type @code{const
3596 char[@var{length}]} so that
3597 copying the address of one into a non-@code{const} @code{char *}
3598 pointer will get a warning; when compiling C++, warn about the
3599 deprecated conversion from string literals to @code{char *}. This
3600 warning, by default, is enabled for C++ programs.
3601 These warnings will help you find at
3602 compile time code that can try to write into a string constant, but
3603 only if you have been very careful about using @code{const} in
3604 declarations and prototypes. Otherwise, it will just be a nuisance;
3605 this is why we did not make @option{-Wall} request these warnings.
3609 @opindex Wno-clobbered
3610 Warn for variables that might be changed by @samp{longjmp} or
3611 @samp{vfork}. This warning is also enabled by @option{-Wextra}.
3614 @opindex Wconversion
3615 @opindex Wno-conversion
3616 Warn for implicit conversions that may alter a value. This includes
3617 conversions between real and integer, like @code{abs (x)} when
3618 @code{x} is @code{double}; conversions between signed and unsigned,
3619 like @code{unsigned ui = -1}; and conversions to smaller types, like
3620 @code{sqrtf (M_PI)}. Do not warn for explicit casts like @code{abs
3621 ((int) x)} and @code{ui = (unsigned) -1}, or if the value is not
3622 changed by the conversion like in @code{abs (2.0)}. Warnings about
3623 conversions between signed and unsigned integers can be disabled by
3624 using @option{-Wno-sign-conversion}.
3626 For C++, also warn for conversions between @code{NULL} and non-pointer
3627 types; confusing overload resolution for user-defined conversions; and
3628 conversions that will never use a type conversion operator:
3629 conversions to @code{void}, the same type, a base class or a reference
3630 to them. Warnings about conversions between signed and unsigned
3631 integers are disabled by default in C++ unless
3632 @option{-Wsign-conversion} is explicitly enabled.
3635 @opindex Wempty-body
3636 @opindex Wno-empty-body
3637 Warn if an empty body occurs in an @samp{if}, @samp{else} or @samp{do
3638 while} statement. Additionally, in C++, warn when an empty body occurs
3639 in a @samp{while} or @samp{for} statement with no whitespacing before
3640 the semicolon. This warning is also enabled by @option{-Wextra}.
3642 @item -Wsign-compare
3643 @opindex Wsign-compare
3644 @opindex Wno-sign-compare
3645 @cindex warning for comparison of signed and unsigned values
3646 @cindex comparison of signed and unsigned values, warning
3647 @cindex signed and unsigned values, comparison warning
3648 Warn when a comparison between signed and unsigned values could produce
3649 an incorrect result when the signed value is converted to unsigned.
3650 This warning is also enabled by @option{-Wextra}; to get the other warnings
3651 of @option{-Wextra} without this warning, use @samp{-Wextra -Wno-sign-compare}.
3653 @item -Wsign-conversion
3654 @opindex Wsign-conversion
3655 @opindex Wno-sign-conversion
3656 Warn for implicit conversions that may change the sign of an integer
3657 value, like assigning a signed integer expression to an unsigned
3658 integer variable. An explicit cast silences the warning. In C, this
3659 option is enabled also by @option{-Wconversion}.
3663 @opindex Wno-address
3664 Warn about suspicious uses of memory addresses. These include using
3665 the address of a function in a conditional expression, such as
3666 @code{void func(void); if (func)}, and comparisons against the memory
3667 address of a string literal, such as @code{if (x == "abc")}. Such
3668 uses typically indicate a programmer error: the address of a function
3669 always evaluates to true, so their use in a conditional usually
3670 indicate that the programmer forgot the parentheses in a function
3671 call; and comparisons against string literals result in unspecified
3672 behavior and are not portable in C, so they usually indicate that the
3673 programmer intended to use @code{strcmp}. This warning is enabled by
3677 @opindex Wlogical-op
3678 @opindex Wno-logical-op
3679 Warn about suspicious uses of logical operators in expressions.
3680 This includes using logical operators in contexts where a
3681 bit-wise operator is likely to be expected.
3683 @item -Waggregate-return
3684 @opindex Waggregate-return
3685 @opindex Wno-aggregate-return
3686 Warn if any functions that return structures or unions are defined or
3687 called. (In languages where you can return an array, this also elicits
3690 @item -Wno-attributes
3691 @opindex Wno-attributes
3692 @opindex Wattributes
3693 Do not warn if an unexpected @code{__attribute__} is used, such as
3694 unrecognized attributes, function attributes applied to variables,
3695 etc. This will not stop errors for incorrect use of supported
3698 @item -Wstrict-prototypes @r{(C and Objective-C only)}
3699 @opindex Wstrict-prototypes
3700 @opindex Wno-strict-prototypes
3701 Warn if a function is declared or defined without specifying the
3702 argument types. (An old-style function definition is permitted without
3703 a warning if preceded by a declaration which specifies the argument
3706 @item -Wold-style-declaration @r{(C and Objective-C only)}
3707 @opindex Wold-style-declaration
3708 @opindex Wno-old-style-declaration
3709 Warn for obsolescent usages, according to the C Standard, in a
3710 declaration. For example, warn if storage-class specifiers like
3711 @code{static} are not the first things in a declaration. This warning
3712 is also enabled by @option{-Wextra}.
3714 @item -Wold-style-definition @r{(C and Objective-C only)}
3715 @opindex Wold-style-definition
3716 @opindex Wno-old-style-definition
3717 Warn if an old-style function definition is used. A warning is given
3718 even if there is a previous prototype.
3720 @item -Wmissing-parameter-type @r{(C and Objective-C only)}
3721 @opindex Wmissing-parameter-type
3722 @opindex Wno-missing-parameter-type
3723 A function parameter is declared without a type specifier in K&R-style
3730 This warning is also enabled by @option{-Wextra}.
3732 @item -Wmissing-prototypes @r{(C and Objective-C only)}
3733 @opindex Wmissing-prototypes
3734 @opindex Wno-missing-prototypes
3735 Warn if a global function is defined without a previous prototype
3736 declaration. This warning is issued even if the definition itself
3737 provides a prototype. The aim is to detect global functions that fail
3738 to be declared in header files.
3740 @item -Wmissing-declarations
3741 @opindex Wmissing-declarations
3742 @opindex Wno-missing-declarations
3743 Warn if a global function is defined without a previous declaration.
3744 Do so even if the definition itself provides a prototype.
3745 Use this option to detect global functions that are not declared in
3746 header files. In C++, no warnings are issued for function templates,
3747 or for inline functions, or for functions in anonymous namespaces.
3749 @item -Wmissing-field-initializers
3750 @opindex Wmissing-field-initializers
3751 @opindex Wno-missing-field-initializers
3755 Warn if a structure's initializer has some fields missing. For
3756 example, the following code would cause such a warning, because
3757 @code{x.h} is implicitly zero:
3760 struct s @{ int f, g, h; @};
3761 struct s x = @{ 3, 4 @};
3764 This option does not warn about designated initializers, so the following
3765 modification would not trigger a warning:
3768 struct s @{ int f, g, h; @};
3769 struct s x = @{ .f = 3, .g = 4 @};
3772 This warning is included in @option{-Wextra}. To get other @option{-Wextra}
3773 warnings without this one, use @samp{-Wextra -Wno-missing-field-initializers}.
3775 @item -Wmissing-noreturn
3776 @opindex Wmissing-noreturn
3777 @opindex Wno-missing-noreturn
3778 Warn about functions which might be candidates for attribute @code{noreturn}.
3779 Note these are only possible candidates, not absolute ones. Care should
3780 be taken to manually verify functions actually do not ever return before
3781 adding the @code{noreturn} attribute, otherwise subtle code generation
3782 bugs could be introduced. You will not get a warning for @code{main} in
3783 hosted C environments.
3785 @item -Wmissing-format-attribute
3786 @opindex Wmissing-format-attribute
3787 @opindex Wno-missing-format-attribute
3790 Warn about function pointers which might be candidates for @code{format}
3791 attributes. Note these are only possible candidates, not absolute ones.
3792 GCC will guess that function pointers with @code{format} attributes that
3793 are used in assignment, initialization, parameter passing or return
3794 statements should have a corresponding @code{format} attribute in the
3795 resulting type. I.e.@: the left-hand side of the assignment or
3796 initialization, the type of the parameter variable, or the return type
3797 of the containing function respectively should also have a @code{format}
3798 attribute to avoid the warning.
3800 GCC will also warn about function definitions which might be
3801 candidates for @code{format} attributes. Again, these are only
3802 possible candidates. GCC will guess that @code{format} attributes
3803 might be appropriate for any function that calls a function like
3804 @code{vprintf} or @code{vscanf}, but this might not always be the
3805 case, and some functions for which @code{format} attributes are
3806 appropriate may not be detected.
3808 @item -Wno-multichar
3809 @opindex Wno-multichar
3811 Do not warn if a multicharacter constant (@samp{'FOOF'}) is used.
3812 Usually they indicate a typo in the user's code, as they have
3813 implementation-defined values, and should not be used in portable code.
3815 @item -Wnormalized=<none|id|nfc|nfkc>
3816 @opindex Wnormalized=
3819 @cindex character set, input normalization
3820 In ISO C and ISO C++, two identifiers are different if they are
3821 different sequences of characters. However, sometimes when characters
3822 outside the basic ASCII character set are used, you can have two
3823 different character sequences that look the same. To avoid confusion,
3824 the ISO 10646 standard sets out some @dfn{normalization rules} which
3825 when applied ensure that two sequences that look the same are turned into
3826 the same sequence. GCC can warn you if you are using identifiers which
3827 have not been normalized; this option controls that warning.
3829 There are four levels of warning that GCC supports. The default is
3830 @option{-Wnormalized=nfc}, which warns about any identifier which is
3831 not in the ISO 10646 ``C'' normalized form, @dfn{NFC}. NFC is the
3832 recommended form for most uses.
3834 Unfortunately, there are some characters which ISO C and ISO C++ allow
3835 in identifiers that when turned into NFC aren't allowable as
3836 identifiers. That is, there's no way to use these symbols in portable
3837 ISO C or C++ and have all your identifiers in NFC@.
3838 @option{-Wnormalized=id} suppresses the warning for these characters.
3839 It is hoped that future versions of the standards involved will correct
3840 this, which is why this option is not the default.
3842 You can switch the warning off for all characters by writing
3843 @option{-Wnormalized=none}. You would only want to do this if you
3844 were using some other normalization scheme (like ``D''), because
3845 otherwise you can easily create bugs that are literally impossible to see.
3847 Some characters in ISO 10646 have distinct meanings but look identical
3848 in some fonts or display methodologies, especially once formatting has
3849 been applied. For instance @code{\u207F}, ``SUPERSCRIPT LATIN SMALL
3850 LETTER N'', will display just like a regular @code{n} which has been
3851 placed in a superscript. ISO 10646 defines the @dfn{NFKC}
3852 normalization scheme to convert all these into a standard form as
3853 well, and GCC will warn if your code is not in NFKC if you use
3854 @option{-Wnormalized=nfkc}. This warning is comparable to warning
3855 about every identifier that contains the letter O because it might be
3856 confused with the digit 0, and so is not the default, but may be
3857 useful as a local coding convention if the programming environment is
3858 unable to be fixed to display these characters distinctly.
3860 @item -Wno-deprecated-declarations
3861 @opindex Wno-deprecated-declarations
3862 @opindex Wdeprecated-declarations
3863 Do not warn about uses of functions (@pxref{Function Attributes}),
3864 variables (@pxref{Variable Attributes}), and types (@pxref{Type
3865 Attributes}) marked as deprecated by using the @code{deprecated}
3869 @opindex Wno-overflow
3871 Do not warn about compile-time overflow in constant expressions.
3873 @item -Woverride-init @r{(C and Objective-C only)}
3874 @opindex Woverride-init
3875 @opindex Wno-override-init
3879 Warn if an initialized field without side effects is overridden when
3880 using designated initializers (@pxref{Designated Inits, , Designated
3883 This warning is included in @option{-Wextra}. To get other
3884 @option{-Wextra} warnings without this one, use @samp{-Wextra
3885 -Wno-override-init}.
3890 Warn if a structure is given the packed attribute, but the packed
3891 attribute has no effect on the layout or size of the structure.
3892 Such structures may be mis-aligned for little benefit. For
3893 instance, in this code, the variable @code{f.x} in @code{struct bar}
3894 will be misaligned even though @code{struct bar} does not itself
3895 have the packed attribute:
3902 @} __attribute__((packed));
3913 Warn if padding is included in a structure, either to align an element
3914 of the structure or to align the whole structure. Sometimes when this
3915 happens it is possible to rearrange the fields of the structure to
3916 reduce the padding and so make the structure smaller.
3918 @item -Wredundant-decls
3919 @opindex Wredundant-decls
3920 @opindex Wno-redundant-decls
3921 Warn if anything is declared more than once in the same scope, even in
3922 cases where multiple declaration is valid and changes nothing.
3924 @item -Wnested-externs @r{(C and Objective-C only)}
3925 @opindex Wnested-externs
3926 @opindex Wno-nested-externs
3927 Warn if an @code{extern} declaration is encountered within a function.
3929 @item -Wunreachable-code
3930 @opindex Wunreachable-code
3931 @opindex Wno-unreachable-code
3932 Warn if the compiler detects that code will never be executed.
3934 This option is intended to warn when the compiler detects that at
3935 least a whole line of source code will never be executed, because
3936 some condition is never satisfied or because it is after a
3937 procedure that never returns.
3939 It is possible for this option to produce a warning even though there
3940 are circumstances under which part of the affected line can be executed,
3941 so care should be taken when removing apparently-unreachable code.
3943 For instance, when a function is inlined, a warning may mean that the
3944 line is unreachable in only one inlined copy of the function.
3946 This option is not made part of @option{-Wall} because in a debugging
3947 version of a program there is often substantial code which checks
3948 correct functioning of the program and is, hopefully, unreachable
3949 because the program does work. Another common use of unreachable
3950 code is to provide behavior which is selectable at compile-time.
3955 Warn if a function can not be inlined and it was declared as inline.
3956 Even with this option, the compiler will not warn about failures to
3957 inline functions declared in system headers.
3959 The compiler uses a variety of heuristics to determine whether or not
3960 to inline a function. For example, the compiler takes into account
3961 the size of the function being inlined and the amount of inlining
3962 that has already been done in the current function. Therefore,
3963 seemingly insignificant changes in the source program can cause the
3964 warnings produced by @option{-Winline} to appear or disappear.
3966 @item -Wno-invalid-offsetof @r{(C++ and Objective-C++ only)}
3967 @opindex Wno-invalid-offsetof
3968 @opindex Winvalid-offsetof
3969 Suppress warnings from applying the @samp{offsetof} macro to a non-POD
3970 type. According to the 1998 ISO C++ standard, applying @samp{offsetof}
3971 to a non-POD type is undefined. In existing C++ implementations,
3972 however, @samp{offsetof} typically gives meaningful results even when
3973 applied to certain kinds of non-POD types. (Such as a simple
3974 @samp{struct} that fails to be a POD type only by virtue of having a
3975 constructor.) This flag is for users who are aware that they are
3976 writing nonportable code and who have deliberately chosen to ignore the
3979 The restrictions on @samp{offsetof} may be relaxed in a future version
3980 of the C++ standard.
3982 @item -Wno-int-to-pointer-cast @r{(C and Objective-C only)}
3983 @opindex Wno-int-to-pointer-cast
3984 @opindex Wint-to-pointer-cast
3985 Suppress warnings from casts to pointer type of an integer of a
3988 @item -Wno-pointer-to-int-cast @r{(C and Objective-C only)}
3989 @opindex Wno-pointer-to-int-cast
3990 @opindex Wpointer-to-int-cast
3991 Suppress warnings from casts from a pointer to an integer type of a
3995 @opindex Winvalid-pch
3996 @opindex Wno-invalid-pch
3997 Warn if a precompiled header (@pxref{Precompiled Headers}) is found in
3998 the search path but can't be used.
4002 @opindex Wno-long-long
4003 Warn if @samp{long long} type is used. This is default. To inhibit
4004 the warning messages, use @option{-Wno-long-long}. Flags
4005 @option{-Wlong-long} and @option{-Wno-long-long} are taken into account
4006 only when @option{-pedantic} flag is used.
4008 @item -Wvariadic-macros
4009 @opindex Wvariadic-macros
4010 @opindex Wno-variadic-macros
4011 Warn if variadic macros are used in pedantic ISO C90 mode, or the GNU
4012 alternate syntax when in pedantic ISO C99 mode. This is default.
4013 To inhibit the warning messages, use @option{-Wno-variadic-macros}.
4018 Warn if variable length array is used in the code.
4019 @option{-Wno-vla} will prevent the @option{-pedantic} warning of
4020 the variable length array.
4022 @item -Wvolatile-register-var
4023 @opindex Wvolatile-register-var
4024 @opindex Wno-volatile-register-var
4025 Warn if a register variable is declared volatile. The volatile
4026 modifier does not inhibit all optimizations that may eliminate reads
4027 and/or writes to register variables. This warning is enabled by
4030 @item -Wdisabled-optimization
4031 @opindex Wdisabled-optimization
4032 @opindex Wno-disabled-optimization
4033 Warn if a requested optimization pass is disabled. This warning does
4034 not generally indicate that there is anything wrong with your code; it
4035 merely indicates that GCC's optimizers were unable to handle the code
4036 effectively. Often, the problem is that your code is too big or too
4037 complex; GCC will refuse to optimize programs when the optimization
4038 itself is likely to take inordinate amounts of time.
4040 @item -Wpointer-sign @r{(C and Objective-C only)}
4041 @opindex Wpointer-sign
4042 @opindex Wno-pointer-sign
4043 Warn for pointer argument passing or assignment with different signedness.
4044 This option is only supported for C and Objective-C@. It is implied by
4045 @option{-Wall} and by @option{-pedantic}, which can be disabled with
4046 @option{-Wno-pointer-sign}.
4048 @item -Wstack-protector
4049 @opindex Wstack-protector
4050 @opindex Wno-stack-protector
4051 This option is only active when @option{-fstack-protector} is active. It
4052 warns about functions that will not be protected against stack smashing.
4054 @item -Woverlength-strings
4055 @opindex Woverlength-strings
4056 @opindex Wno-overlength-strings
4057 Warn about string constants which are longer than the ``minimum
4058 maximum'' length specified in the C standard. Modern compilers
4059 generally allow string constants which are much longer than the
4060 standard's minimum limit, but very portable programs should avoid
4061 using longer strings.
4063 The limit applies @emph{after} string constant concatenation, and does
4064 not count the trailing NUL@. In C89, the limit was 509 characters; in
4065 C99, it was raised to 4095. C++98 does not specify a normative
4066 minimum maximum, so we do not diagnose overlength strings in C++@.
4068 This option is implied by @option{-pedantic}, and can be disabled with
4069 @option{-Wno-overlength-strings}.
4072 @node Debugging Options
4073 @section Options for Debugging Your Program or GCC
4074 @cindex options, debugging
4075 @cindex debugging information options
4077 GCC has various special options that are used for debugging
4078 either your program or GCC:
4083 Produce debugging information in the operating system's native format
4084 (stabs, COFF, XCOFF, or DWARF 2)@. GDB can work with this debugging
4087 On most systems that use stabs format, @option{-g} enables use of extra
4088 debugging information that only GDB can use; this extra information
4089 makes debugging work better in GDB but will probably make other debuggers
4091 refuse to read the program. If you want to control for certain whether
4092 to generate the extra information, use @option{-gstabs+}, @option{-gstabs},
4093 @option{-gxcoff+}, @option{-gxcoff}, or @option{-gvms} (see below).
4095 GCC allows you to use @option{-g} with
4096 @option{-O}. The shortcuts taken by optimized code may occasionally
4097 produce surprising results: some variables you declared may not exist
4098 at all; flow of control may briefly move where you did not expect it;
4099 some statements may not be executed because they compute constant
4100 results or their values were already at hand; some statements may
4101 execute in different places because they were moved out of loops.
4103 Nevertheless it proves possible to debug optimized output. This makes
4104 it reasonable to use the optimizer for programs that might have bugs.
4106 The following options are useful when GCC is generated with the
4107 capability for more than one debugging format.
4111 Produce debugging information for use by GDB@. This means to use the
4112 most expressive format available (DWARF 2, stabs, or the native format
4113 if neither of those are supported), including GDB extensions if at all
4118 Produce debugging information in stabs format (if that is supported),
4119 without GDB extensions. This is the format used by DBX on most BSD
4120 systems. On MIPS, Alpha and System V Release 4 systems this option
4121 produces stabs debugging output which is not understood by DBX or SDB@.
4122 On System V Release 4 systems this option requires the GNU assembler.
4124 @item -feliminate-unused-debug-symbols
4125 @opindex feliminate-unused-debug-symbols
4126 Produce debugging information in stabs format (if that is supported),
4127 for only symbols that are actually used.
4129 @item -femit-class-debug-always
4130 Instead of emitting debugging information for a C++ class in only one
4131 object file, emit it in all object files using the class. This option
4132 should be used only with debuggers that are unable to handle the way GCC
4133 normally emits debugging information for classes because using this
4134 option will increase the size of debugging information by as much as a
4139 Produce debugging information in stabs format (if that is supported),
4140 using GNU extensions understood only by the GNU debugger (GDB)@. The
4141 use of these extensions is likely to make other debuggers crash or
4142 refuse to read the program.
4146 Produce debugging information in COFF format (if that is supported).
4147 This is the format used by SDB on most System V systems prior to
4152 Produce debugging information in XCOFF format (if that is supported).
4153 This is the format used by the DBX debugger on IBM RS/6000 systems.
4157 Produce debugging information in XCOFF format (if that is supported),
4158 using GNU extensions understood only by the GNU debugger (GDB)@. The
4159 use of these extensions is likely to make other debuggers crash or
4160 refuse to read the program, and may cause assemblers other than the GNU
4161 assembler (GAS) to fail with an error.
4165 Produce debugging information in DWARF version 2 format (if that is
4166 supported). This is the format used by DBX on IRIX 6. With this
4167 option, GCC uses features of DWARF version 3 when they are useful;
4168 version 3 is upward compatible with version 2, but may still cause
4169 problems for older debuggers.
4173 Produce debugging information in VMS debug format (if that is
4174 supported). This is the format used by DEBUG on VMS systems.
4177 @itemx -ggdb@var{level}
4178 @itemx -gstabs@var{level}
4179 @itemx -gcoff@var{level}
4180 @itemx -gxcoff@var{level}
4181 @itemx -gvms@var{level}
4182 Request debugging information and also use @var{level} to specify how
4183 much information. The default level is 2.
4185 Level 0 produces no debug information at all. Thus, @option{-g0} negates
4188 Level 1 produces minimal information, enough for making backtraces in
4189 parts of the program that you don't plan to debug. This includes
4190 descriptions of functions and external variables, but no information
4191 about local variables and no line numbers.
4193 Level 3 includes extra information, such as all the macro definitions
4194 present in the program. Some debuggers support macro expansion when
4195 you use @option{-g3}.
4197 @option{-gdwarf-2} does not accept a concatenated debug level, because
4198 GCC used to support an option @option{-gdwarf} that meant to generate
4199 debug information in version 1 of the DWARF format (which is very
4200 different from version 2), and it would have been too confusing. That
4201 debug format is long obsolete, but the option cannot be changed now.
4202 Instead use an additional @option{-g@var{level}} option to change the
4203 debug level for DWARF2.
4205 @item -feliminate-dwarf2-dups
4206 @opindex feliminate-dwarf2-dups
4207 Compress DWARF2 debugging information by eliminating duplicated
4208 information about each symbol. This option only makes sense when
4209 generating DWARF2 debugging information with @option{-gdwarf-2}.
4211 @item -femit-struct-debug-baseonly
4212 Emit debug information for struct-like types
4213 only when the base name of the compilation source file
4214 matches the base name of file in which the struct was defined.
4216 This option substantially reduces the size of debugging information,
4217 but at significant potential loss in type information to the debugger.
4218 See @option{-femit-struct-debug-reduced} for a less aggressive option.
4219 See @option{-femit-struct-debug-detailed} for more detailed control.
4221 This option works only with DWARF 2.
4223 @item -femit-struct-debug-reduced
4224 Emit debug information for struct-like types
4225 only when the base name of the compilation source file
4226 matches the base name of file in which the type was defined,
4227 unless the struct is a template or defined in a system header.
4229 This option significantly reduces the size of debugging information,
4230 with some potential loss in type information to the debugger.
4231 See @option{-femit-struct-debug-baseonly} for a more aggressive option.
4232 See @option{-femit-struct-debug-detailed} for more detailed control.
4234 This option works only with DWARF 2.
4236 @item -femit-struct-debug-detailed@r{[}=@var{spec-list}@r{]}
4237 Specify the struct-like types
4238 for which the compiler will generate debug information.
4239 The intent is to reduce duplicate struct debug information
4240 between different object files within the same program.
4242 This option is a detailed version of
4243 @option{-femit-struct-debug-reduced} and @option{-femit-struct-debug-baseonly},
4244 which will serve for most needs.
4246 A specification has the syntax
4247 [@samp{dir:}|@samp{ind:}][@samp{ord:}|@samp{gen:}](@samp{any}|@samp{sys}|@samp{base}|@samp{none})
4249 The optional first word limits the specification to
4250 structs that are used directly (@samp{dir:}) or used indirectly (@samp{ind:}).
4251 A struct type is used directly when it is the type of a variable, member.
4252 Indirect uses arise through pointers to structs.
4253 That is, when use of an incomplete struct would be legal, the use is indirect.
4255 @samp{struct one direct; struct two * indirect;}.
4257 The optional second word limits the specification to
4258 ordinary structs (@samp{ord:}) or generic structs (@samp{gen:}).
4259 Generic structs are a bit complicated to explain.
4260 For C++, these are non-explicit specializations of template classes,
4261 or non-template classes within the above.
4262 Other programming languages have generics,
4263 but @samp{-femit-struct-debug-detailed} does not yet implement them.
4265 The third word specifies the source files for those
4266 structs for which the compiler will emit debug information.
4267 The values @samp{none} and @samp{any} have the normal meaning.
4268 The value @samp{base} means that
4269 the base of name of the file in which the type declaration appears
4270 must match the base of the name of the main compilation file.
4271 In practice, this means that
4272 types declared in @file{foo.c} and @file{foo.h} will have debug information,
4273 but types declared in other header will not.
4274 The value @samp{sys} means those types satisfying @samp{base}
4275 or declared in system or compiler headers.
4277 You may need to experiment to determine the best settings for your application.
4279 The default is @samp{-femit-struct-debug-detailed=all}.
4281 This option works only with DWARF 2.
4283 @item -fno-merge-debug-strings
4284 @opindex fmerge-debug-strings
4285 @opindex fno-merge-debug-strings
4286 Direct the linker to merge together strings which are identical in
4287 different object files. This is not supported by all assemblers or
4288 linker. This decreases the size of the debug information in the
4289 output file at the cost of increasing link processing time. This is
4292 @item -fdebug-prefix-map=@var{old}=@var{new}
4293 @opindex fdebug-prefix-map
4294 When compiling files in directory @file{@var{old}}, record debugging
4295 information describing them as in @file{@var{new}} instead.
4297 @cindex @command{prof}
4300 Generate extra code to write profile information suitable for the
4301 analysis program @command{prof}. You must use this option when compiling
4302 the source files you want data about, and you must also use it when
4305 @cindex @command{gprof}
4308 Generate extra code to write profile information suitable for the
4309 analysis program @command{gprof}. You must use this option when compiling
4310 the source files you want data about, and you must also use it when
4315 Makes the compiler print out each function name as it is compiled, and
4316 print some statistics about each pass when it finishes.
4319 @opindex ftime-report
4320 Makes the compiler print some statistics about the time consumed by each
4321 pass when it finishes.
4324 @opindex fmem-report
4325 Makes the compiler print some statistics about permanent memory
4326 allocation when it finishes.
4328 @item -fpre-ipa-mem-report
4329 @opindex fpre-ipa-mem-report
4330 @item -fpost-ipa-mem-report
4331 @opindex fpost-ipa-mem-report
4332 Makes the compiler print some statistics about permanent memory
4333 allocation before or after interprocedural optimization.
4335 @item -fprofile-arcs
4336 @opindex fprofile-arcs
4337 Add code so that program flow @dfn{arcs} are instrumented. During
4338 execution the program records how many times each branch and call is
4339 executed and how many times it is taken or returns. When the compiled
4340 program exits it saves this data to a file called
4341 @file{@var{auxname}.gcda} for each source file. The data may be used for
4342 profile-directed optimizations (@option{-fbranch-probabilities}), or for
4343 test coverage analysis (@option{-ftest-coverage}). Each object file's
4344 @var{auxname} is generated from the name of the output file, if
4345 explicitly specified and it is not the final executable, otherwise it is
4346 the basename of the source file. In both cases any suffix is removed
4347 (e.g.@: @file{foo.gcda} for input file @file{dir/foo.c}, or
4348 @file{dir/foo.gcda} for output file specified as @option{-o dir/foo.o}).
4349 @xref{Cross-profiling}.
4351 @cindex @command{gcov}
4355 This option is used to compile and link code instrumented for coverage
4356 analysis. The option is a synonym for @option{-fprofile-arcs}
4357 @option{-ftest-coverage} (when compiling) and @option{-lgcov} (when
4358 linking). See the documentation for those options for more details.
4363 Compile the source files with @option{-fprofile-arcs} plus optimization
4364 and code generation options. For test coverage analysis, use the
4365 additional @option{-ftest-coverage} option. You do not need to profile
4366 every source file in a program.
4369 Link your object files with @option{-lgcov} or @option{-fprofile-arcs}
4370 (the latter implies the former).
4373 Run the program on a representative workload to generate the arc profile
4374 information. This may be repeated any number of times. You can run
4375 concurrent instances of your program, and provided that the file system
4376 supports locking, the data files will be correctly updated. Also
4377 @code{fork} calls are detected and correctly handled (double counting
4381 For profile-directed optimizations, compile the source files again with
4382 the same optimization and code generation options plus
4383 @option{-fbranch-probabilities} (@pxref{Optimize Options,,Options that
4384 Control Optimization}).
4387 For test coverage analysis, use @command{gcov} to produce human readable
4388 information from the @file{.gcno} and @file{.gcda} files. Refer to the
4389 @command{gcov} documentation for further information.
4393 With @option{-fprofile-arcs}, for each function of your program GCC
4394 creates a program flow graph, then finds a spanning tree for the graph.
4395 Only arcs that are not on the spanning tree have to be instrumented: the
4396 compiler adds code to count the number of times that these arcs are
4397 executed. When an arc is the only exit or only entrance to a block, the
4398 instrumentation code can be added to the block; otherwise, a new basic
4399 block must be created to hold the instrumentation code.
4402 @item -ftest-coverage
4403 @opindex ftest-coverage
4404 Produce a notes file that the @command{gcov} code-coverage utility
4405 (@pxref{Gcov,, @command{gcov}---a Test Coverage Program}) can use to
4406 show program coverage. Each source file's note file is called
4407 @file{@var{auxname}.gcno}. Refer to the @option{-fprofile-arcs} option
4408 above for a description of @var{auxname} and instructions on how to
4409 generate test coverage data. Coverage data will match the source files
4410 more closely, if you do not optimize.
4412 @item -fdbg-cnt-list
4413 @opindex fdbg-cnt-list
4414 Print the name and the counter upperbound for all debug counters.
4416 @item -fdbg-cnt=@var{counter-value-list}
4418 Set the internal debug counter upperbound. @var{counter-value-list}
4419 is a comma-separated list of @var{name}:@var{value} pairs
4420 which sets the upperbound of each debug counter @var{name} to @var{value}.
4421 All debug counters have the initial upperbound of @var{UINT_MAX},
4422 thus dbg_cnt() returns true always unless the upperbound is set by this option.
4423 e.g. With -fdbg-cnt=dce:10,tail_call:0
4424 dbg_cnt(dce) will return true only for first 10 invocations
4425 and dbg_cnt(tail_call) will return false always.
4427 @item -d@var{letters}
4428 @item -fdump-rtl-@var{pass}
4430 Says to make debugging dumps during compilation at times specified by
4431 @var{letters}. This is used for debugging the RTL-based passes of the
4432 compiler. The file names for most of the dumps are made by appending a
4433 pass number and a word to the @var{dumpname}. @var{dumpname} is generated
4434 from the name of the output file, if explicitly specified and it is not
4435 an executable, otherwise it is the basename of the source file. These
4436 switches may have different effects when @option{-E} is used for
4439 Most debug dumps can be enabled either passing a letter to the @option{-d}
4440 option, or with a long @option{-fdump-rtl} switch; here are the possible
4441 letters for use in @var{letters} and @var{pass}, and their meanings:
4446 Annotate the assembler output with miscellaneous debugging information.
4449 @itemx -fdump-rtl-bbro
4451 @opindex fdump-rtl-bbro
4452 Dump after block reordering, to @file{@var{file}.148r.bbro}.
4455 @itemx -fdump-rtl-combine
4457 @opindex fdump-rtl-combine
4458 Dump after the RTL instruction combination pass, to the file
4459 @file{@var{file}.129r.combine}.
4462 @itemx -fdump-rtl-ce1
4463 @itemx -fdump-rtl-ce2
4465 @opindex fdump-rtl-ce1
4466 @opindex fdump-rtl-ce2
4467 @option{-dC} and @option{-fdump-rtl-ce1} enable dumping after the
4468 first if conversion, to the file @file{@var{file}.117r.ce1}. @option{-dC}
4469 and @option{-fdump-rtl-ce2} enable dumping after the second if
4470 conversion, to the file @file{@var{file}.130r.ce2}.
4473 @itemx -fdump-rtl-btl
4474 @itemx -fdump-rtl-dbr
4476 @opindex fdump-rtl-btl
4477 @opindex fdump-rtl-dbr
4478 @option{-dd} and @option{-fdump-rtl-btl} enable dumping after branch
4479 target load optimization, to @file{@var{file}.31.btl}. @option{-dd}
4480 and @option{-fdump-rtl-dbr} enable dumping after delayed branch
4481 scheduling, to @file{@var{file}.36.dbr}.
4485 Dump all macro definitions, at the end of preprocessing, in addition to
4489 @itemx -fdump-rtl-ce3
4491 @opindex fdump-rtl-ce3
4492 Dump after the third if conversion, to @file{@var{file}.146r.ce3}.
4495 @itemx -fdump-rtl-cfg
4496 @itemx -fdump-rtl-life
4498 @opindex fdump-rtl-cfg
4499 @opindex fdump-rtl-life
4500 @option{-df} and @option{-fdump-rtl-cfg} enable dumping after control
4501 and data flow analysis, to @file{@var{file}.116r.cfg}. @option{-df}
4502 and @option{-fdump-rtl-cfg} enable dumping dump after life analysis,
4503 to @file{@var{file}.128r.life1} and @file{@var{file}.135r.life2}.
4506 @itemx -fdump-rtl-greg
4508 @opindex fdump-rtl-greg
4509 Dump after global register allocation, to @file{@var{file}.139r.greg}.
4512 @itemx -fdump-rtl-gcse
4513 @itemx -fdump-rtl-bypass
4515 @opindex fdump-rtl-gcse
4516 @opindex fdump-rtl-bypass
4517 @option{-dG} and @option{-fdump-rtl-gcse} enable dumping after GCSE, to
4518 @file{@var{file}.114r.gcse}. @option{-dG} and @option{-fdump-rtl-bypass}
4519 enable dumping after jump bypassing and control flow optimizations, to
4520 @file{@var{file}.115r.bypass}.
4523 @itemx -fdump-rtl-eh
4525 @opindex fdump-rtl-eh
4526 Dump after finalization of EH handling code, to @file{@var{file}.02.eh}.
4529 @itemx -fdump-rtl-sibling
4531 @opindex fdump-rtl-sibling
4532 Dump after sibling call optimizations, to @file{@var{file}.106r.sibling}.
4535 @itemx -fdump-rtl-jump
4537 @opindex fdump-rtl-jump
4538 Dump after the first jump optimization, to @file{@var{file}.112r.jump}.
4541 @itemx -fdump-rtl-stack
4543 @opindex fdump-rtl-stack
4544 Dump after conversion from GCC's "flat register file" registers to the
4545 x87's stack-like registers, to @file{@var{file}.152r.stack}.
4548 @itemx -fdump-rtl-lreg
4550 @opindex fdump-rtl-lreg
4551 Dump after local register allocation, to @file{@var{file}.138r.lreg}.
4554 @itemx -fdump-rtl-loop2
4556 @opindex fdump-rtl-loop2
4557 @option{-dL} and @option{-fdump-rtl-loop2} enable dumping after the
4558 loop optimization pass, to @file{@var{file}.119r.loop2},
4559 @file{@var{file}.120r.loop2_init},
4560 @file{@var{file}.121r.loop2_invariant}, and
4561 @file{@var{file}.125r.loop2_done}.
4564 @itemx -fdump-rtl-sms
4566 @opindex fdump-rtl-sms
4567 Dump after modulo scheduling, to @file{@var{file}.136r.sms}.
4570 @itemx -fdump-rtl-mach
4572 @opindex fdump-rtl-mach
4573 Dump after performing the machine dependent reorganization pass, to
4574 @file{@var{file}.155r.mach} if that pass exists.
4577 @itemx -fdump-rtl-rnreg
4579 @opindex fdump-rtl-rnreg
4580 Dump after register renumbering, to @file{@var{file}.147r.rnreg}.
4583 @itemx -fdump-rtl-regmove
4585 @opindex fdump-rtl-regmove
4586 Dump after the register move pass, to @file{@var{file}.132r.regmove}.
4589 @itemx -fdump-rtl-postreload
4591 @opindex fdump-rtl-postreload
4592 Dump after post-reload optimizations, to @file{@var{file}.24.postreload}.
4595 @itemx -fdump-rtl-expand
4597 @opindex fdump-rtl-expand
4598 Dump after RTL generation, to @file{@var{file}.104r.expand}.
4601 @itemx -fdump-rtl-sched2
4603 @opindex fdump-rtl-sched2
4604 Dump after the second scheduling pass, to @file{@var{file}.149r.sched2}.
4607 @itemx -fdump-rtl-cse
4609 @opindex fdump-rtl-cse
4610 Dump after CSE (including the jump optimization that sometimes follows
4611 CSE), to @file{@var{file}.113r.cse}.
4614 @itemx -fdump-rtl-sched1
4616 @opindex fdump-rtl-sched1
4617 Dump after the first scheduling pass, to @file{@var{file}.136r.sched1}.
4620 @itemx -fdump-rtl-cse2
4622 @opindex fdump-rtl-cse2
4623 Dump after the second CSE pass (including the jump optimization that
4624 sometimes follows CSE), to @file{@var{file}.127r.cse2}.
4627 @itemx -fdump-rtl-tracer
4629 @opindex fdump-rtl-tracer
4630 Dump after running tracer, to @file{@var{file}.118r.tracer}.
4633 @itemx -fdump-rtl-vpt
4634 @itemx -fdump-rtl-vartrack
4636 @opindex fdump-rtl-vpt
4637 @opindex fdump-rtl-vartrack
4638 @option{-dV} and @option{-fdump-rtl-vpt} enable dumping after the value
4639 profile transformations, to @file{@var{file}.10.vpt}. @option{-dV}
4640 and @option{-fdump-rtl-vartrack} enable dumping after variable tracking,
4641 to @file{@var{file}.154r.vartrack}.
4644 @itemx -fdump-rtl-flow2
4646 @opindex fdump-rtl-flow2
4647 Dump after the second flow pass, to @file{@var{file}.142r.flow2}.
4650 @itemx -fdump-rtl-peephole2
4652 @opindex fdump-rtl-peephole2
4653 Dump after the peephole pass, to @file{@var{file}.145r.peephole2}.
4656 @itemx -fdump-rtl-web
4658 @opindex fdump-rtl-web
4659 Dump after live range splitting, to @file{@var{file}.126r.web}.
4662 @itemx -fdump-rtl-all
4664 @opindex fdump-rtl-all
4665 Produce all the dumps listed above.
4669 Produce a core dump whenever an error occurs.
4673 Print statistics on memory usage, at the end of the run, to
4678 Annotate the assembler output with a comment indicating which
4679 pattern and alternative was used. The length of each instruction is
4684 Dump the RTL in the assembler output as a comment before each instruction.
4685 Also turns on @option{-dp} annotation.
4689 For each of the other indicated dump files (either with @option{-d} or
4690 @option{-fdump-rtl-@var{pass}}), dump a representation of the control flow
4691 graph suitable for viewing with VCG to @file{@var{file}.@var{pass}.vcg}.
4695 Just generate RTL for a function instead of compiling it. Usually used
4696 with @samp{r} (@option{-fdump-rtl-expand}).
4700 Dump debugging information during parsing, to standard error.
4704 @opindex fdump-noaddr
4705 When doing debugging dumps (see @option{-d} option above), suppress
4706 address output. This makes it more feasible to use diff on debugging
4707 dumps for compiler invocations with different compiler binaries and/or
4708 different text / bss / data / heap / stack / dso start locations.
4710 @item -fdump-unnumbered
4711 @opindex fdump-unnumbered
4712 When doing debugging dumps (see @option{-d} option above), suppress instruction
4713 numbers and address output. This makes it more feasible to
4714 use diff on debugging dumps for compiler invocations with different
4715 options, in particular with and without @option{-g}.
4717 @item -fdump-translation-unit @r{(C++ only)}
4718 @itemx -fdump-translation-unit-@var{options} @r{(C++ only)}
4719 @opindex fdump-translation-unit
4720 Dump a representation of the tree structure for the entire translation
4721 unit to a file. The file name is made by appending @file{.tu} to the
4722 source file name. If the @samp{-@var{options}} form is used, @var{options}
4723 controls the details of the dump as described for the
4724 @option{-fdump-tree} options.
4726 @item -fdump-class-hierarchy @r{(C++ only)}
4727 @itemx -fdump-class-hierarchy-@var{options} @r{(C++ only)}
4728 @opindex fdump-class-hierarchy
4729 Dump a representation of each class's hierarchy and virtual function
4730 table layout to a file. The file name is made by appending @file{.class}
4731 to the source file name. If the @samp{-@var{options}} form is used,
4732 @var{options} controls the details of the dump as described for the
4733 @option{-fdump-tree} options.
4735 @item -fdump-ipa-@var{switch}
4737 Control the dumping at various stages of inter-procedural analysis
4738 language tree to a file. The file name is generated by appending a switch
4739 specific suffix to the source file name. The following dumps are possible:
4743 Enables all inter-procedural analysis dumps.
4746 Dumps information about call-graph optimization, unused function removal,
4747 and inlining decisions.
4750 Dump after function inlining.
4754 @item -fdump-tree-@var{switch}
4755 @itemx -fdump-tree-@var{switch}-@var{options}
4757 Control the dumping at various stages of processing the intermediate
4758 language tree to a file. The file name is generated by appending a switch
4759 specific suffix to the source file name. If the @samp{-@var{options}}
4760 form is used, @var{options} is a list of @samp{-} separated options that
4761 control the details of the dump. Not all options are applicable to all
4762 dumps, those which are not meaningful will be ignored. The following
4763 options are available
4767 Print the address of each node. Usually this is not meaningful as it
4768 changes according to the environment and source file. Its primary use
4769 is for tying up a dump file with a debug environment.
4771 Inhibit dumping of members of a scope or body of a function merely
4772 because that scope has been reached. Only dump such items when they
4773 are directly reachable by some other path. When dumping pretty-printed
4774 trees, this option inhibits dumping the bodies of control structures.
4776 Print a raw representation of the tree. By default, trees are
4777 pretty-printed into a C-like representation.
4779 Enable more detailed dumps (not honored by every dump option).
4781 Enable dumping various statistics about the pass (not honored by every dump
4784 Enable showing basic block boundaries (disabled in raw dumps).
4786 Enable showing virtual operands for every statement.
4788 Enable showing line numbers for statements.
4790 Enable showing the unique ID (@code{DECL_UID}) for each variable.
4792 Turn on all options, except @option{raw}, @option{slim} and @option{lineno}.
4795 The following tree dumps are possible:
4799 Dump before any tree based optimization, to @file{@var{file}.original}.
4802 Dump after all tree based optimization, to @file{@var{file}.optimized}.
4805 @opindex fdump-tree-gimple
4806 Dump each function before and after the gimplification pass to a file. The
4807 file name is made by appending @file{.gimple} to the source file name.
4810 @opindex fdump-tree-cfg
4811 Dump the control flow graph of each function to a file. The file name is
4812 made by appending @file{.cfg} to the source file name.
4815 @opindex fdump-tree-vcg
4816 Dump the control flow graph of each function to a file in VCG format. The
4817 file name is made by appending @file{.vcg} to the source file name. Note
4818 that if the file contains more than one function, the generated file cannot
4819 be used directly by VCG@. You will need to cut and paste each function's
4820 graph into its own separate file first.
4823 @opindex fdump-tree-ch
4824 Dump each function after copying loop headers. The file name is made by
4825 appending @file{.ch} to the source file name.
4828 @opindex fdump-tree-ssa
4829 Dump SSA related information to a file. The file name is made by appending
4830 @file{.ssa} to the source file name.
4833 @opindex fdump-tree-salias
4834 Dump structure aliasing variable information to a file. This file name
4835 is made by appending @file{.salias} to the source file name.
4838 @opindex fdump-tree-alias
4839 Dump aliasing information for each function. The file name is made by
4840 appending @file{.alias} to the source file name.
4843 @opindex fdump-tree-ccp
4844 Dump each function after CCP@. The file name is made by appending
4845 @file{.ccp} to the source file name.
4848 @opindex fdump-tree-storeccp
4849 Dump each function after STORE-CCP@. The file name is made by appending
4850 @file{.storeccp} to the source file name.
4853 @opindex fdump-tree-pre
4854 Dump trees after partial redundancy elimination. The file name is made
4855 by appending @file{.pre} to the source file name.
4858 @opindex fdump-tree-fre
4859 Dump trees after full redundancy elimination. The file name is made
4860 by appending @file{.fre} to the source file name.
4863 @opindex fdump-tree-copyprop
4864 Dump trees after copy propagation. The file name is made
4865 by appending @file{.copyprop} to the source file name.
4867 @item store_copyprop
4868 @opindex fdump-tree-store_copyprop
4869 Dump trees after store copy-propagation. The file name is made
4870 by appending @file{.store_copyprop} to the source file name.
4873 @opindex fdump-tree-dce
4874 Dump each function after dead code elimination. The file name is made by
4875 appending @file{.dce} to the source file name.
4878 @opindex fdump-tree-mudflap
4879 Dump each function after adding mudflap instrumentation. The file name is
4880 made by appending @file{.mudflap} to the source file name.
4883 @opindex fdump-tree-sra
4884 Dump each function after performing scalar replacement of aggregates. The
4885 file name is made by appending @file{.sra} to the source file name.
4888 @opindex fdump-tree-sink
4889 Dump each function after performing code sinking. The file name is made
4890 by appending @file{.sink} to the source file name.
4893 @opindex fdump-tree-dom
4894 Dump each function after applying dominator tree optimizations. The file
4895 name is made by appending @file{.dom} to the source file name.
4898 @opindex fdump-tree-dse
4899 Dump each function after applying dead store elimination. The file
4900 name is made by appending @file{.dse} to the source file name.
4903 @opindex fdump-tree-phiopt
4904 Dump each function after optimizing PHI nodes into straightline code. The file
4905 name is made by appending @file{.phiopt} to the source file name.
4908 @opindex fdump-tree-forwprop
4909 Dump each function after forward propagating single use variables. The file
4910 name is made by appending @file{.forwprop} to the source file name.
4913 @opindex fdump-tree-copyrename
4914 Dump each function after applying the copy rename optimization. The file
4915 name is made by appending @file{.copyrename} to the source file name.
4918 @opindex fdump-tree-nrv
4919 Dump each function after applying the named return value optimization on
4920 generic trees. The file name is made by appending @file{.nrv} to the source
4924 @opindex fdump-tree-vect
4925 Dump each function after applying vectorization of loops. The file name is
4926 made by appending @file{.vect} to the source file name.
4929 @opindex fdump-tree-vrp
4930 Dump each function after Value Range Propagation (VRP). The file name
4931 is made by appending @file{.vrp} to the source file name.
4934 @opindex fdump-tree-all
4935 Enable all the available tree dumps with the flags provided in this option.
4938 @item -ftree-vectorizer-verbose=@var{n}
4939 @opindex ftree-vectorizer-verbose
4940 This option controls the amount of debugging output the vectorizer prints.
4941 This information is written to standard error, unless
4942 @option{-fdump-tree-all} or @option{-fdump-tree-vect} is specified,
4943 in which case it is output to the usual dump listing file, @file{.vect}.
4944 For @var{n}=0 no diagnostic information is reported.
4945 If @var{n}=1 the vectorizer reports each loop that got vectorized,
4946 and the total number of loops that got vectorized.
4947 If @var{n}=2 the vectorizer also reports non-vectorized loops that passed
4948 the first analysis phase (vect_analyze_loop_form) - i.e.@: countable,
4949 inner-most, single-bb, single-entry/exit loops. This is the same verbosity
4950 level that @option{-fdump-tree-vect-stats} uses.
4951 Higher verbosity levels mean either more information dumped for each
4952 reported loop, or same amount of information reported for more loops:
4953 If @var{n}=3, alignment related information is added to the reports.
4954 If @var{n}=4, data-references related information (e.g.@: memory dependences,
4955 memory access-patterns) is added to the reports.
4956 If @var{n}=5, the vectorizer reports also non-vectorized inner-most loops
4957 that did not pass the first analysis phase (i.e., may not be countable, or
4958 may have complicated control-flow).
4959 If @var{n}=6, the vectorizer reports also non-vectorized nested loops.
4960 For @var{n}=7, all the information the vectorizer generates during its
4961 analysis and transformation is reported. This is the same verbosity level
4962 that @option{-fdump-tree-vect-details} uses.
4964 @item -frandom-seed=@var{string}
4965 @opindex frandom-string
4966 This option provides a seed that GCC uses when it would otherwise use
4967 random numbers. It is used to generate certain symbol names
4968 that have to be different in every compiled file. It is also used to
4969 place unique stamps in coverage data files and the object files that
4970 produce them. You can use the @option{-frandom-seed} option to produce
4971 reproducibly identical object files.
4973 The @var{string} should be different for every file you compile.
4975 @item -fsched-verbose=@var{n}
4976 @opindex fsched-verbose
4977 On targets that use instruction scheduling, this option controls the
4978 amount of debugging output the scheduler prints. This information is
4979 written to standard error, unless @option{-dS} or @option{-dR} is
4980 specified, in which case it is output to the usual dump
4981 listing file, @file{.sched} or @file{.sched2} respectively. However
4982 for @var{n} greater than nine, the output is always printed to standard
4985 For @var{n} greater than zero, @option{-fsched-verbose} outputs the
4986 same information as @option{-dRS}. For @var{n} greater than one, it
4987 also output basic block probabilities, detailed ready list information
4988 and unit/insn info. For @var{n} greater than two, it includes RTL
4989 at abort point, control-flow and regions info. And for @var{n} over
4990 four, @option{-fsched-verbose} also includes dependence info.
4994 Store the usual ``temporary'' intermediate files permanently; place them
4995 in the current directory and name them based on the source file. Thus,
4996 compiling @file{foo.c} with @samp{-c -save-temps} would produce files
4997 @file{foo.i} and @file{foo.s}, as well as @file{foo.o}. This creates a
4998 preprocessed @file{foo.i} output file even though the compiler now
4999 normally uses an integrated preprocessor.
5001 When used in combination with the @option{-x} command line option,
5002 @option{-save-temps} is sensible enough to avoid over writing an
5003 input source file with the same extension as an intermediate file.
5004 The corresponding intermediate file may be obtained by renaming the
5005 source file before using @option{-save-temps}.
5009 Report the CPU time taken by each subprocess in the compilation
5010 sequence. For C source files, this is the compiler proper and assembler
5011 (plus the linker if linking is done). The output looks like this:
5018 The first number on each line is the ``user time'', that is time spent
5019 executing the program itself. The second number is ``system time'',
5020 time spent executing operating system routines on behalf of the program.
5021 Both numbers are in seconds.
5023 @item -fvar-tracking
5024 @opindex fvar-tracking
5025 Run variable tracking pass. It computes where variables are stored at each
5026 position in code. Better debugging information is then generated
5027 (if the debugging information format supports this information).
5029 It is enabled by default when compiling with optimization (@option{-Os},
5030 @option{-O}, @option{-O2}, @dots{}), debugging information (@option{-g}) and
5031 the debug info format supports it.
5033 @item -print-file-name=@var{library}
5034 @opindex print-file-name
5035 Print the full absolute name of the library file @var{library} that
5036 would be used when linking---and don't do anything else. With this
5037 option, GCC does not compile or link anything; it just prints the
5040 @item -print-multi-directory
5041 @opindex print-multi-directory
5042 Print the directory name corresponding to the multilib selected by any
5043 other switches present in the command line. This directory is supposed
5044 to exist in @env{GCC_EXEC_PREFIX}.
5046 @item -print-multi-lib
5047 @opindex print-multi-lib
5048 Print the mapping from multilib directory names to compiler switches
5049 that enable them. The directory name is separated from the switches by
5050 @samp{;}, and each switch starts with an @samp{@@} instead of the
5051 @samp{-}, without spaces between multiple switches. This is supposed to
5052 ease shell-processing.
5054 @item -print-prog-name=@var{program}
5055 @opindex print-prog-name
5056 Like @option{-print-file-name}, but searches for a program such as @samp{cpp}.
5058 @item -print-libgcc-file-name
5059 @opindex print-libgcc-file-name
5060 Same as @option{-print-file-name=libgcc.a}.
5062 This is useful when you use @option{-nostdlib} or @option{-nodefaultlibs}
5063 but you do want to link with @file{libgcc.a}. You can do
5066 gcc -nostdlib @var{files}@dots{} `gcc -print-libgcc-file-name`
5069 @item -print-search-dirs
5070 @opindex print-search-dirs
5071 Print the name of the configured installation directory and a list of
5072 program and library directories @command{gcc} will search---and don't do anything else.
5074 This is useful when @command{gcc} prints the error message
5075 @samp{installation problem, cannot exec cpp0: No such file or directory}.
5076 To resolve this you either need to put @file{cpp0} and the other compiler
5077 components where @command{gcc} expects to find them, or you can set the environment
5078 variable @env{GCC_EXEC_PREFIX} to the directory where you installed them.
5079 Don't forget the trailing @samp{/}.
5080 @xref{Environment Variables}.
5082 @item -print-sysroot-headers-suffix
5083 @opindex print-sysroot-headers-suffix
5084 Print the suffix added to the target sysroot when searching for
5085 headers, or give an error if the compiler is not configured with such
5086 a suffix---and don't do anything else.
5089 @opindex dumpmachine
5090 Print the compiler's target machine (for example,
5091 @samp{i686-pc-linux-gnu})---and don't do anything else.
5094 @opindex dumpversion
5095 Print the compiler version (for example, @samp{3.0})---and don't do
5100 Print the compiler's built-in specs---and don't do anything else. (This
5101 is used when GCC itself is being built.) @xref{Spec Files}.
5103 @item -feliminate-unused-debug-types
5104 @opindex feliminate-unused-debug-types
5105 Normally, when producing DWARF2 output, GCC will emit debugging
5106 information for all types declared in a compilation
5107 unit, regardless of whether or not they are actually used
5108 in that compilation unit. Sometimes this is useful, such as
5109 if, in the debugger, you want to cast a value to a type that is
5110 not actually used in your program (but is declared). More often,
5111 however, this results in a significant amount of wasted space.
5112 With this option, GCC will avoid producing debug symbol output
5113 for types that are nowhere used in the source file being compiled.
5116 @node Optimize Options
5117 @section Options That Control Optimization
5118 @cindex optimize options
5119 @cindex options, optimization
5121 These options control various sorts of optimizations.
5123 Without any optimization option, the compiler's goal is to reduce the
5124 cost of compilation and to make debugging produce the expected
5125 results. Statements are independent: if you stop the program with a
5126 breakpoint between statements, you can then assign a new value to any
5127 variable or change the program counter to any other statement in the
5128 function and get exactly the results you would expect from the source
5131 Turning on optimization flags makes the compiler attempt to improve
5132 the performance and/or code size at the expense of compilation time
5133 and possibly the ability to debug the program.
5135 The compiler performs optimization based on the knowledge it has of
5136 the program. Optimization levels @option{-O} and above, in
5137 particular, enable @emph{unit-at-a-time} mode, which allows the
5138 compiler to consider information gained from later functions in
5139 the file when compiling a function. Compiling multiple files at
5140 once to a single output file in @emph{unit-at-a-time} mode allows
5141 the compiler to use information gained from all of the files when
5142 compiling each of them.
5144 Not all optimizations are controlled directly by a flag. Only
5145 optimizations that have a flag are listed.
5152 Optimize. Optimizing compilation takes somewhat more time, and a lot
5153 more memory for a large function.
5155 With @option{-O}, the compiler tries to reduce code size and execution
5156 time, without performing any optimizations that take a great deal of
5159 @option{-O} turns on the following optimization flags:
5162 -fcprop-registers @gol
5165 -fdelayed-branch @gol
5167 -fguess-branch-probability @gol
5168 -fif-conversion2 @gol
5169 -fif-conversion @gol
5170 -finline-small-functions @gol
5171 -fipa-pure-const @gol
5172 -fipa-reference @gol
5174 -fsplit-wide-types @gol
5177 -ftree-copyrename @gol
5179 -ftree-dominator-opts @gol
5186 @option{-O} also turns on @option{-fomit-frame-pointer} on machines
5187 where doing so does not interfere with debugging.
5191 Optimize even more. GCC performs nearly all supported optimizations
5192 that do not involve a space-speed tradeoff. The compiler does not
5193 perform loop unrolling or function inlining when you specify @option{-O2}.
5194 As compared to @option{-O}, this option increases both compilation time
5195 and the performance of the generated code.
5197 @option{-O2} turns on all optimization flags specified by @option{-O}. It
5198 also turns on the following optimization flags:
5199 @gccoptlist{-fthread-jumps @gol
5200 -falign-functions -falign-jumps @gol
5201 -falign-loops -falign-labels @gol
5204 -fcse-follow-jumps -fcse-skip-blocks @gol
5205 -fdelete-null-pointer-checks @gol
5206 -fexpensive-optimizations @gol
5207 -fgcse -fgcse-lm @gol
5208 -foptimize-sibling-calls @gol
5211 -freorder-blocks -freorder-functions @gol
5212 -frerun-cse-after-loop @gol
5213 -fsched-interblock -fsched-spec @gol
5214 -fschedule-insns -fschedule-insns2 @gol
5215 -fstrict-aliasing -fstrict-overflow @gol
5219 Please note the warning under @option{-fgcse} about
5220 invoking @option{-O2} on programs that use computed gotos.
5224 Optimize yet more. @option{-O3} turns on all optimizations specified by
5225 @option{-O2} and also turns on the @option{-finline-functions},
5226 @option{-funswitch-loops}, @option{-fpredictive-commoning} and
5227 @option{-fgcse-after-reload} options.
5231 Reduce compilation time and make debugging produce the expected
5232 results. This is the default.
5236 Optimize for size. @option{-Os} enables all @option{-O2} optimizations that
5237 do not typically increase code size. It also performs further
5238 optimizations designed to reduce code size.
5240 @option{-Os} disables the following optimization flags:
5241 @gccoptlist{-falign-functions -falign-jumps -falign-loops @gol
5242 -falign-labels -freorder-blocks -freorder-blocks-and-partition @gol
5243 -fprefetch-loop-arrays -ftree-vect-loop-version}
5245 If you use multiple @option{-O} options, with or without level numbers,
5246 the last such option is the one that is effective.
5249 Options of the form @option{-f@var{flag}} specify machine-independent
5250 flags. Most flags have both positive and negative forms; the negative
5251 form of @option{-ffoo} would be @option{-fno-foo}. In the table
5252 below, only one of the forms is listed---the one you typically will
5253 use. You can figure out the other form by either removing @samp{no-}
5256 The following options control specific optimizations. They are either
5257 activated by @option{-O} options or are related to ones that are. You
5258 can use the following flags in the rare cases when ``fine-tuning'' of
5259 optimizations to be performed is desired.
5262 @item -fno-default-inline
5263 @opindex fno-default-inline
5264 Do not make member functions inline by default merely because they are
5265 defined inside the class scope (C++ only). Otherwise, when you specify
5266 @w{@option{-O}}, member functions defined inside class scope are compiled
5267 inline by default; i.e., you don't need to add @samp{inline} in front of
5268 the member function name.
5270 @item -fno-defer-pop
5271 @opindex fno-defer-pop
5272 Always pop the arguments to each function call as soon as that function
5273 returns. For machines which must pop arguments after a function call,
5274 the compiler normally lets arguments accumulate on the stack for several
5275 function calls and pops them all at once.
5277 Disabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
5279 @item -fforward-propagate
5280 @opindex fforward-propagate
5281 Perform a forward propagation pass on RTL@. The pass tries to combine two
5282 instructions and checks if the result can be simplified. If loop unrolling
5283 is active, two passes are performed and the second is scheduled after
5286 This option is enabled by default at optimization levels @option{-O2},
5287 @option{-O3}, @option{-Os}.
5289 @item -fomit-frame-pointer
5290 @opindex fomit-frame-pointer
5291 Don't keep the frame pointer in a register for functions that
5292 don't need one. This avoids the instructions to save, set up and
5293 restore frame pointers; it also makes an extra register available
5294 in many functions. @strong{It also makes debugging impossible on
5297 On some machines, such as the VAX, this flag has no effect, because
5298 the standard calling sequence automatically handles the frame pointer
5299 and nothing is saved by pretending it doesn't exist. The
5300 machine-description macro @code{FRAME_POINTER_REQUIRED} controls
5301 whether a target machine supports this flag. @xref{Registers,,Register
5302 Usage, gccint, GNU Compiler Collection (GCC) Internals}.
5304 Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
5306 @item -foptimize-sibling-calls
5307 @opindex foptimize-sibling-calls
5308 Optimize sibling and tail recursive calls.
5310 Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
5314 Don't pay attention to the @code{inline} keyword. Normally this option
5315 is used to keep the compiler from expanding any functions inline.
5316 Note that if you are not optimizing, no functions can be expanded inline.
5318 @item -finline-small-functions
5319 @opindex finline-small-functions
5320 Integrate functions into their callers when their body is smaller than expected
5321 function call code (so overall size of program gets smaller). The compiler
5322 heuristically decides which functions are simple enough to be worth integrating
5325 Enabled at level @option{-O2}.
5327 @item -finline-functions
5328 @opindex finline-functions
5329 Integrate all simple functions into their callers. The compiler
5330 heuristically decides which functions are simple enough to be worth
5331 integrating in this way.
5333 If all calls to a given function are integrated, and the function is
5334 declared @code{static}, then the function is normally not output as
5335 assembler code in its own right.
5337 Enabled at level @option{-O3}.
5339 @item -finline-functions-called-once
5340 @opindex finline-functions-called-once
5341 Consider all @code{static} functions called once for inlining into their
5342 caller even if they are not marked @code{inline}. If a call to a given
5343 function is integrated, then the function is not output as assembler code
5346 Enabled if @option{-funit-at-a-time} is enabled.
5348 @item -fearly-inlining
5349 @opindex fearly-inlining
5350 Inline functions marked by @code{always_inline} and functions whose body seems
5351 smaller than the function call overhead early before doing
5352 @option{-fprofile-generate} instrumentation and real inlining pass. Doing so
5353 makes profiling significantly cheaper and usually inlining faster on programs
5354 having large chains of nested wrapper functions.
5358 @item -finline-limit=@var{n}
5359 @opindex finline-limit
5360 By default, GCC limits the size of functions that can be inlined. This flag
5361 allows coarse control of this limit. @var{n} is the size of functions that
5362 can be inlined in number of pseudo instructions.
5364 Inlining is actually controlled by a number of parameters, which may be
5365 specified individually by using @option{--param @var{name}=@var{value}}.
5366 The @option{-finline-limit=@var{n}} option sets some of these parameters
5370 @item max-inline-insns-single
5371 is set to @var{n}/2.
5372 @item max-inline-insns-auto
5373 is set to @var{n}/2.
5376 See below for a documentation of the individual
5377 parameters controlling inlining and for the defaults of these parameters.
5379 @emph{Note:} there may be no value to @option{-finline-limit} that results
5380 in default behavior.
5382 @emph{Note:} pseudo instruction represents, in this particular context, an
5383 abstract measurement of function's size. In no way does it represent a count
5384 of assembly instructions and as such its exact meaning might change from one
5385 release to an another.
5387 @item -fkeep-inline-functions
5388 @opindex fkeep-inline-functions
5389 In C, emit @code{static} functions that are declared @code{inline}
5390 into the object file, even if the function has been inlined into all
5391 of its callers. This switch does not affect functions using the
5392 @code{extern inline} extension in GNU C89@. In C++, emit any and all
5393 inline functions into the object file.
5395 @item -fkeep-static-consts
5396 @opindex fkeep-static-consts
5397 Emit variables declared @code{static const} when optimization isn't turned
5398 on, even if the variables aren't referenced.
5400 GCC enables this option by default. If you want to force the compiler to
5401 check if the variable was referenced, regardless of whether or not
5402 optimization is turned on, use the @option{-fno-keep-static-consts} option.
5404 @item -fmerge-constants
5405 @opindex fmerge-constants
5406 Attempt to merge identical constants (string constants and floating point
5407 constants) across compilation units.
5409 This option is the default for optimized compilation if the assembler and
5410 linker support it. Use @option{-fno-merge-constants} to inhibit this
5413 Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
5415 @item -fmerge-all-constants
5416 @opindex fmerge-all-constants
5417 Attempt to merge identical constants and identical variables.
5419 This option implies @option{-fmerge-constants}. In addition to
5420 @option{-fmerge-constants} this considers e.g.@: even constant initialized
5421 arrays or initialized constant variables with integral or floating point
5422 types. Languages like C or C++ require each non-automatic variable to
5423 have distinct location, so using this option will result in non-conforming
5426 @item -fmodulo-sched
5427 @opindex fmodulo-sched
5428 Perform swing modulo scheduling immediately before the first scheduling
5429 pass. This pass looks at innermost loops and reorders their
5430 instructions by overlapping different iterations.
5432 @item -fmodulo-sched-allow-regmoves
5433 @opindex fmodulo-sched-allow-regmoves
5434 Perform more aggressive SMS based modulo scheduling with register moves
5435 allowed. By setting this flag certain anti-dependences edges will be
5436 deleted which will trigger the generation of reg-moves based on the
5437 life-range analysis. This option is effective only with
5438 @option{-fmodulo-sched} enabled.
5440 @item -fno-branch-count-reg
5441 @opindex fno-branch-count-reg
5442 Do not use ``decrement and branch'' instructions on a count register,
5443 but instead generate a sequence of instructions that decrement a
5444 register, compare it against zero, then branch based upon the result.
5445 This option is only meaningful on architectures that support such
5446 instructions, which include x86, PowerPC, IA-64 and S/390.
5448 The default is @option{-fbranch-count-reg}.
5450 @item -fno-function-cse
5451 @opindex fno-function-cse
5452 Do not put function addresses in registers; make each instruction that
5453 calls a constant function contain the function's address explicitly.
5455 This option results in less efficient code, but some strange hacks
5456 that alter the assembler output may be confused by the optimizations
5457 performed when this option is not used.
5459 The default is @option{-ffunction-cse}
5461 @item -fno-zero-initialized-in-bss
5462 @opindex fno-zero-initialized-in-bss
5463 If the target supports a BSS section, GCC by default puts variables that
5464 are initialized to zero into BSS@. This can save space in the resulting
5467 This option turns off this behavior because some programs explicitly
5468 rely on variables going to the data section. E.g., so that the
5469 resulting executable can find the beginning of that section and/or make
5470 assumptions based on that.
5472 The default is @option{-fzero-initialized-in-bss}.
5474 @item -fmudflap -fmudflapth -fmudflapir
5478 @cindex bounds checking
5480 For front-ends that support it (C and C++), instrument all risky
5481 pointer/array dereferencing operations, some standard library
5482 string/heap functions, and some other associated constructs with
5483 range/validity tests. Modules so instrumented should be immune to
5484 buffer overflows, invalid heap use, and some other classes of C/C++
5485 programming errors. The instrumentation relies on a separate runtime
5486 library (@file{libmudflap}), which will be linked into a program if
5487 @option{-fmudflap} is given at link time. Run-time behavior of the
5488 instrumented program is controlled by the @env{MUDFLAP_OPTIONS}
5489 environment variable. See @code{env MUDFLAP_OPTIONS=-help a.out}
5492 Use @option{-fmudflapth} instead of @option{-fmudflap} to compile and to
5493 link if your program is multi-threaded. Use @option{-fmudflapir}, in
5494 addition to @option{-fmudflap} or @option{-fmudflapth}, if
5495 instrumentation should ignore pointer reads. This produces less
5496 instrumentation (and therefore faster execution) and still provides
5497 some protection against outright memory corrupting writes, but allows
5498 erroneously read data to propagate within a program.
5500 @item -fthread-jumps
5501 @opindex fthread-jumps
5502 Perform optimizations where we check to see if a jump branches to a
5503 location where another comparison subsumed by the first is found. If
5504 so, the first branch is redirected to either the destination of the
5505 second branch or a point immediately following it, depending on whether
5506 the condition is known to be true or false.
5508 Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
5510 @item -fsplit-wide-types
5511 @opindex fsplit-wide-types
5512 When using a type that occupies multiple registers, such as @code{long
5513 long} on a 32-bit system, split the registers apart and allocate them
5514 independently. This normally generates better code for those types,
5515 but may make debugging more difficult.
5517 Enabled at levels @option{-O}, @option{-O2}, @option{-O3},
5520 @item -fcse-follow-jumps
5521 @opindex fcse-follow-jumps
5522 In common subexpression elimination (CSE), scan through jump instructions
5523 when the target of the jump is not reached by any other path. For
5524 example, when CSE encounters an @code{if} statement with an
5525 @code{else} clause, CSE will follow the jump when the condition
5528 Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
5530 @item -fcse-skip-blocks
5531 @opindex fcse-skip-blocks
5532 This is similar to @option{-fcse-follow-jumps}, but causes CSE to
5533 follow jumps which conditionally skip over blocks. When CSE
5534 encounters a simple @code{if} statement with no else clause,
5535 @option{-fcse-skip-blocks} causes CSE to follow the jump around the
5536 body of the @code{if}.
5538 Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
5540 @item -frerun-cse-after-loop
5541 @opindex frerun-cse-after-loop
5542 Re-run common subexpression elimination after loop optimizations has been
5545 Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
5549 Perform a global common subexpression elimination pass.
5550 This pass also performs global constant and copy propagation.
5552 @emph{Note:} When compiling a program using computed gotos, a GCC
5553 extension, you may get better runtime performance if you disable
5554 the global common subexpression elimination pass by adding
5555 @option{-fno-gcse} to the command line.
5557 Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
5561 When @option{-fgcse-lm} is enabled, global common subexpression elimination will
5562 attempt to move loads which are only killed by stores into themselves. This
5563 allows a loop containing a load/store sequence to be changed to a load outside
5564 the loop, and a copy/store within the loop.
5566 Enabled by default when gcse is enabled.
5570 When @option{-fgcse-sm} is enabled, a store motion pass is run after
5571 global common subexpression elimination. This pass will attempt to move
5572 stores out of loops. When used in conjunction with @option{-fgcse-lm},
5573 loops containing a load/store sequence can be changed to a load before
5574 the loop and a store after the loop.
5576 Not enabled at any optimization level.
5580 When @option{-fgcse-las} is enabled, the global common subexpression
5581 elimination pass eliminates redundant loads that come after stores to the
5582 same memory location (both partial and full redundancies).
5584 Not enabled at any optimization level.
5586 @item -fgcse-after-reload
5587 @opindex fgcse-after-reload
5588 When @option{-fgcse-after-reload} is enabled, a redundant load elimination
5589 pass is performed after reload. The purpose of this pass is to cleanup
5592 @item -funsafe-loop-optimizations
5593 @opindex funsafe-loop-optimizations
5594 If given, the loop optimizer will assume that loop indices do not
5595 overflow, and that the loops with nontrivial exit condition are not
5596 infinite. This enables a wider range of loop optimizations even if
5597 the loop optimizer itself cannot prove that these assumptions are valid.
5598 Using @option{-Wunsafe-loop-optimizations}, the compiler will warn you
5599 if it finds this kind of loop.
5601 @item -fcrossjumping
5602 @opindex fcrossjumping
5603 Perform cross-jumping transformation. This transformation unifies equivalent code and save code size. The
5604 resulting code may or may not perform better than without cross-jumping.
5606 Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
5608 @item -fauto-inc-dec
5609 @opindex fauto-inc-dec
5610 Combine increments or decrements of addresses with memory accesses.
5611 This pass is always skipped on architectures that do not have
5612 instructions to support this. Enabled by default at @option{-O} and
5613 higher on architectures that support this.
5617 Perform dead code elimination (DCE) on RTL@.
5618 Enabled by default at @option{-O} and higher.
5622 Perform dead store elimination (DSE) on RTL@.
5623 Enabled by default at @option{-O} and higher.
5625 @item -fif-conversion
5626 @opindex fif-conversion
5627 Attempt to transform conditional jumps into branch-less equivalents. This
5628 include use of conditional moves, min, max, set flags and abs instructions, and
5629 some tricks doable by standard arithmetics. The use of conditional execution
5630 on chips where it is available is controlled by @code{if-conversion2}.
5632 Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
5634 @item -fif-conversion2
5635 @opindex fif-conversion2
5636 Use conditional execution (where available) to transform conditional jumps into
5637 branch-less equivalents.
5639 Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
5641 @item -fdelete-null-pointer-checks
5642 @opindex fdelete-null-pointer-checks
5643 Use global dataflow analysis to identify and eliminate useless checks
5644 for null pointers. The compiler assumes that dereferencing a null
5645 pointer would have halted the program. If a pointer is checked after
5646 it has already been dereferenced, it cannot be null.
5648 In some environments, this assumption is not true, and programs can
5649 safely dereference null pointers. Use
5650 @option{-fno-delete-null-pointer-checks} to disable this optimization
5651 for programs which depend on that behavior.
5653 Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
5655 @item -fexpensive-optimizations
5656 @opindex fexpensive-optimizations
5657 Perform a number of minor optimizations that are relatively expensive.
5659 Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
5661 @item -foptimize-register-move
5663 @opindex foptimize-register-move
5665 Attempt to reassign register numbers in move instructions and as
5666 operands of other simple instructions in order to maximize the amount of
5667 register tying. This is especially helpful on machines with two-operand
5670 Note @option{-fregmove} and @option{-foptimize-register-move} are the same
5673 Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
5675 @item -fdelayed-branch
5676 @opindex fdelayed-branch
5677 If supported for the target machine, attempt to reorder instructions
5678 to exploit instruction slots available after delayed branch
5681 Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
5683 @item -fschedule-insns
5684 @opindex fschedule-insns
5685 If supported for the target machine, attempt to reorder instructions to
5686 eliminate execution stalls due to required data being unavailable. This
5687 helps machines that have slow floating point or memory load instructions
5688 by allowing other instructions to be issued until the result of the load
5689 or floating point instruction is required.
5691 Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
5693 @item -fschedule-insns2
5694 @opindex fschedule-insns2
5695 Similar to @option{-fschedule-insns}, but requests an additional pass of
5696 instruction scheduling after register allocation has been done. This is
5697 especially useful on machines with a relatively small number of
5698 registers and where memory load instructions take more than one cycle.
5700 Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
5702 @item -fno-sched-interblock
5703 @opindex fno-sched-interblock
5704 Don't schedule instructions across basic blocks. This is normally
5705 enabled by default when scheduling before register allocation, i.e.@:
5706 with @option{-fschedule-insns} or at @option{-O2} or higher.
5708 @item -fno-sched-spec
5709 @opindex fno-sched-spec
5710 Don't allow speculative motion of non-load instructions. This is normally
5711 enabled by default when scheduling before register allocation, i.e.@:
5712 with @option{-fschedule-insns} or at @option{-O2} or higher.
5714 @item -fsched-spec-load
5715 @opindex fsched-spec-load
5716 Allow speculative motion of some load instructions. This only makes
5717 sense when scheduling before register allocation, i.e.@: with
5718 @option{-fschedule-insns} or at @option{-O2} or higher.
5720 @item -fsched-spec-load-dangerous
5721 @opindex fsched-spec-load-dangerous
5722 Allow speculative motion of more load instructions. This only makes
5723 sense when scheduling before register allocation, i.e.@: with
5724 @option{-fschedule-insns} or at @option{-O2} or higher.
5726 @item -fsched-stalled-insns
5727 @itemx -fsched-stalled-insns=@var{n}
5728 @opindex fsched-stalled-insns
5729 Define how many insns (if any) can be moved prematurely from the queue
5730 of stalled insns into the ready list, during the second scheduling pass.
5731 @option{-fno-sched-stalled-insns} means that no insns will be moved
5732 prematurely, @option{-fsched-stalled-insns=0} means there is no limit
5733 on how many queued insns can be moved prematurely.
5734 @option{-fsched-stalled-insns} without a value is equivalent to
5735 @option{-fsched-stalled-insns=1}.
5737 @item -fsched-stalled-insns-dep
5738 @itemx -fsched-stalled-insns-dep=@var{n}
5739 @opindex fsched-stalled-insns-dep
5740 Define how many insn groups (cycles) will be examined for a dependency
5741 on a stalled insn that is candidate for premature removal from the queue
5742 of stalled insns. This has an effect only during the second scheduling pass,
5743 and only if @option{-fsched-stalled-insns} is used.
5744 @option{-fno-sched-stalled-insns-dep} is equivalent to
5745 @option{-fsched-stalled-insns-dep=0}.
5746 @option{-fsched-stalled-insns-dep} without a value is equivalent to
5747 @option{-fsched-stalled-insns-dep=1}.
5749 @item -fsched2-use-superblocks
5750 @opindex fsched2-use-superblocks
5751 When scheduling after register allocation, do use superblock scheduling
5752 algorithm. Superblock scheduling allows motion across basic block boundaries
5753 resulting on faster schedules. This option is experimental, as not all machine
5754 descriptions used by GCC model the CPU closely enough to avoid unreliable
5755 results from the algorithm.
5757 This only makes sense when scheduling after register allocation, i.e.@: with
5758 @option{-fschedule-insns2} or at @option{-O2} or higher.
5760 @item -fsched2-use-traces
5761 @opindex fsched2-use-traces
5762 Use @option{-fsched2-use-superblocks} algorithm when scheduling after register
5763 allocation and additionally perform code duplication in order to increase the
5764 size of superblocks using tracer pass. See @option{-ftracer} for details on
5767 This mode should produce faster but significantly longer programs. Also
5768 without @option{-fbranch-probabilities} the traces constructed may not
5769 match the reality and hurt the performance. This only makes
5770 sense when scheduling after register allocation, i.e.@: with
5771 @option{-fschedule-insns2} or at @option{-O2} or higher.
5775 Eliminate redundant sign extension instructions and move the non-redundant
5776 ones to optimal placement using lazy code motion (LCM).
5778 @item -freschedule-modulo-scheduled-loops
5779 @opindex freschedule-modulo-scheduled-loops
5780 The modulo scheduling comes before the traditional scheduling, if a loop
5781 was modulo scheduled we may want to prevent the later scheduling passes
5782 from changing its schedule, we use this option to control that.
5784 @item -fcaller-saves
5785 @opindex fcaller-saves
5786 Enable values to be allocated in registers that will be clobbered by
5787 function calls, by emitting extra instructions to save and restore the
5788 registers around such calls. Such allocation is done only when it
5789 seems to result in better code than would otherwise be produced.
5791 This option is always enabled by default on certain machines, usually
5792 those which have no call-preserved registers to use instead.
5794 Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
5796 @item -ftree-reassoc
5797 @opindex ftree-reassoc
5798 Perform reassociation on trees. This flag is enabled by default
5799 at @option{-O} and higher.
5803 Perform partial redundancy elimination (PRE) on trees. This flag is
5804 enabled by default at @option{-O2} and @option{-O3}.
5808 Perform full redundancy elimination (FRE) on trees. The difference
5809 between FRE and PRE is that FRE only considers expressions
5810 that are computed on all paths leading to the redundant computation.
5811 This analysis is faster than PRE, though it exposes fewer redundancies.
5812 This flag is enabled by default at @option{-O} and higher.
5814 @item -ftree-copy-prop
5815 @opindex ftree-copy-prop
5816 Perform copy propagation on trees. This pass eliminates unnecessary
5817 copy operations. This flag is enabled by default at @option{-O} and
5821 @opindex ftree-salias
5822 Perform structural alias analysis on trees. This flag
5823 is enabled by default at @option{-O} and higher.
5825 @item -fipa-pure-const
5826 @opindex fipa-pure-const
5827 Discover which functions are pure or constant.
5828 Enabled by default at @option{-O} and higher.
5830 @item -fipa-reference
5831 @opindex fipa-reference
5832 Discover which static variables do not escape cannot escape the
5834 Enabled by default at @option{-O} and higher.
5836 @item -fipa-struct-reorg
5837 @opindex fipa-struct-reorg
5838 Perform structure reorganization optimization, that change C-like structures
5839 layout in order to better utilize spatial locality. This transformation is
5840 affective for programs containing arrays of structures. Available in two
5841 compilation modes: profile-based (enabled with @option{-fprofile-generate})
5842 or static (which uses built-in heuristics). Require @option{-fipa-type-escape}
5843 to provide the safety of this transformation. It works only in whole program
5844 mode, so it requires @option{-fwhole-program} and @option{-combine} to be
5845 enabled. Structures considered @samp{cold} by this transformation are not
5846 affected (see @option{--param struct-reorg-cold-struct-ratio=@var{value}}).
5848 With this flag, the program debug info reflects a new structure layout.
5852 Perform interprocedural pointer analysis.
5856 Perform interprocedural constant propagation.
5857 This optimization analyzes the program to determine when values passed
5858 to functions are constants and then optimizes accordingly.
5859 This optimization can substantially increase performance
5860 if the application has constants passed to functions, but
5861 because this optimization can create multiple copies of functions,
5862 it may significantly increase code size.
5864 @item -fipa-matrix-reorg
5865 @opindex fipa-matrix-reorg
5866 Perform matrix flattening and transposing.
5867 Matrix flattening tries to replace a m-dimensional matrix
5868 with its equivalent n-dimensional matrix, where n < m.
5869 This reduces the level of indirection needed for accessing the elements
5870 of the matrix. The second optimization is matrix transposing that
5871 attemps to change the order of the matrix's dimensions in order to
5872 improve cache locality.
5873 Both optimizations need fwhole-program flag.
5874 Transposing is enabled only if profiling information is avaliable.
5879 Perform forward store motion on trees. This flag is
5880 enabled by default at @option{-O} and higher.
5884 Perform sparse conditional constant propagation (CCP) on trees. This
5885 pass only operates on local scalar variables and is enabled by default
5886 at @option{-O} and higher.
5888 @item -ftree-store-ccp
5889 @opindex ftree-store-ccp
5890 Perform sparse conditional constant propagation (CCP) on trees. This
5891 pass operates on both local scalar variables and memory stores and
5892 loads (global variables, structures, arrays, etc). This flag is
5893 enabled by default at @option{-O2} and higher.
5897 Perform dead code elimination (DCE) on trees. This flag is enabled by
5898 default at @option{-O} and higher.
5900 @item -ftree-dominator-opts
5901 @opindex ftree-dominator-opts
5902 Perform a variety of simple scalar cleanups (constant/copy
5903 propagation, redundancy elimination, range propagation and expression
5904 simplification) based on a dominator tree traversal. This also
5905 performs jump threading (to reduce jumps to jumps). This flag is
5906 enabled by default at @option{-O} and higher.
5910 Perform dead store elimination (DSE) on trees. A dead store is a store into
5911 a memory location which will later be overwritten by another store without
5912 any intervening loads. In this case the earlier store can be deleted. This
5913 flag is enabled by default at @option{-O} and higher.
5917 Perform loop header copying on trees. This is beneficial since it increases
5918 effectiveness of code motion optimizations. It also saves one jump. This flag
5919 is enabled by default at @option{-O} and higher. It is not enabled
5920 for @option{-Os}, since it usually increases code size.
5922 @item -ftree-loop-optimize
5923 @opindex ftree-loop-optimize
5924 Perform loop optimizations on trees. This flag is enabled by default
5925 at @option{-O} and higher.
5927 @item -ftree-loop-linear
5928 @opindex ftree-loop-linear
5929 Perform linear loop transformations on tree. This flag can improve cache
5930 performance and allow further loop optimizations to take place.
5932 @item -fcheck-data-deps
5933 @opindex fcheck-data-deps
5934 Compare the results of several data dependence analyzers. This option
5935 is used for debugging the data dependence analyzers.
5937 @item -ftree-loop-distribution
5938 Perform loop distribution. This flag can improve cache performance on
5939 big loop bodies and allow further loop optimizations, like
5940 parallelization or vectorization, to take place.
5942 @item -ftree-loop-im
5943 @opindex ftree-loop-im
5944 Perform loop invariant motion on trees. This pass moves only invariants that
5945 would be hard to handle at RTL level (function calls, operations that expand to
5946 nontrivial sequences of insns). With @option{-funswitch-loops} it also moves
5947 operands of conditions that are invariant out of the loop, so that we can use
5948 just trivial invariantness analysis in loop unswitching. The pass also includes
5951 @item -ftree-loop-ivcanon
5952 @opindex ftree-loop-ivcanon
5953 Create a canonical counter for number of iterations in the loop for that
5954 determining number of iterations requires complicated analysis. Later
5955 optimizations then may determine the number easily. Useful especially
5956 in connection with unrolling.
5960 Perform induction variable optimizations (strength reduction, induction
5961 variable merging and induction variable elimination) on trees.
5963 @item -ftree-parallelize-loops=n
5964 @opindex ftree-parallelize-loops
5965 Parallelize loops, i.e., split their iteration space to run in n threads.
5966 This is only possible for loops whose iterations are independent
5967 and can be arbitrarily reordered. The optimization is only
5968 profitable on multiprocessor machines, for loops that are CPU-intensive,
5969 rather than constrained e.g.@: by memory bandwidth. This option
5970 implies @option{-pthread}, and thus is only supported on targets
5971 that have support for @option{-pthread}.
5975 Perform scalar replacement of aggregates. This pass replaces structure
5976 references with scalars to prevent committing structures to memory too
5977 early. This flag is enabled by default at @option{-O} and higher.
5979 @item -ftree-copyrename
5980 @opindex ftree-copyrename
5981 Perform copy renaming on trees. This pass attempts to rename compiler
5982 temporaries to other variables at copy locations, usually resulting in
5983 variable names which more closely resemble the original variables. This flag
5984 is enabled by default at @option{-O} and higher.
5988 Perform temporary expression replacement during the SSA->normal phase. Single
5989 use/single def temporaries are replaced at their use location with their
5990 defining expression. This results in non-GIMPLE code, but gives the expanders
5991 much more complex trees to work on resulting in better RTL generation. This is
5992 enabled by default at @option{-O} and higher.
5994 @item -ftree-vectorize
5995 @opindex ftree-vectorize
5996 Perform loop vectorization on trees.
5998 @item -ftree-vect-loop-version
5999 @opindex ftree-vect-loop-version
6000 Perform loop versioning when doing loop vectorization on trees. When a loop
6001 appears to be vectorizable except that data alignment or data dependence cannot
6002 be determined at compile time then vectorized and non-vectorized versions of
6003 the loop are generated along with runtime checks for alignment or dependence
6004 to control which version is executed. This option is enabled by default
6005 except at level @option{-Os} where it is disabled.
6007 @item -fvect-cost-model
6008 @opindex fvect-cost-model
6009 Enable cost model for vectorization.
6013 Perform Value Range Propagation on trees. This is similar to the
6014 constant propagation pass, but instead of values, ranges of values are
6015 propagated. This allows the optimizers to remove unnecessary range
6016 checks like array bound checks and null pointer checks. This is
6017 enabled by default at @option{-O2} and higher. Null pointer check
6018 elimination is only done if @option{-fdelete-null-pointer-checks} is
6023 Perform tail duplication to enlarge superblock size. This transformation
6024 simplifies the control flow of the function allowing other optimizations to do
6027 @item -funroll-loops
6028 @opindex funroll-loops
6029 Unroll loops whose number of iterations can be determined at compile
6030 time or upon entry to the loop. @option{-funroll-loops} implies
6031 @option{-frerun-cse-after-loop}. This option makes code larger,
6032 and may or may not make it run faster.
6034 @item -funroll-all-loops
6035 @opindex funroll-all-loops
6036 Unroll all loops, even if their number of iterations is uncertain when
6037 the loop is entered. This usually makes programs run more slowly.
6038 @option{-funroll-all-loops} implies the same options as
6039 @option{-funroll-loops},
6041 @item -fsplit-ivs-in-unroller
6042 @opindex fsplit-ivs-in-unroller
6043 Enables expressing of values of induction variables in later iterations
6044 of the unrolled loop using the value in the first iteration. This breaks
6045 long dependency chains, thus improving efficiency of the scheduling passes.
6047 Combination of @option{-fweb} and CSE is often sufficient to obtain the
6048 same effect. However in cases the loop body is more complicated than
6049 a single basic block, this is not reliable. It also does not work at all
6050 on some of the architectures due to restrictions in the CSE pass.
6052 This optimization is enabled by default.
6054 @item -fvariable-expansion-in-unroller
6055 @opindex fvariable-expansion-in-unroller
6056 With this option, the compiler will create multiple copies of some
6057 local variables when unrolling a loop which can result in superior code.
6059 @item -fpredictive-commoning
6060 @opindex fpredictive-commoning
6061 Perform predictive commoning optimization, i.e., reusing computations
6062 (especially memory loads and stores) performed in previous
6063 iterations of loops.
6065 This option is enabled at level @option{-O3}.
6067 @item -fprefetch-loop-arrays
6068 @opindex fprefetch-loop-arrays
6069 If supported by the target machine, generate instructions to prefetch
6070 memory to improve the performance of loops that access large arrays.
6072 This option may generate better or worse code; results are highly
6073 dependent on the structure of loops within the source code.
6075 Disabled at level @option{-Os}.
6078 @itemx -fno-peephole2
6079 @opindex fno-peephole
6080 @opindex fno-peephole2
6081 Disable any machine-specific peephole optimizations. The difference
6082 between @option{-fno-peephole} and @option{-fno-peephole2} is in how they
6083 are implemented in the compiler; some targets use one, some use the
6084 other, a few use both.
6086 @option{-fpeephole} is enabled by default.
6087 @option{-fpeephole2} enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
6089 @item -fno-guess-branch-probability
6090 @opindex fno-guess-branch-probability
6091 Do not guess branch probabilities using heuristics.
6093 GCC will use heuristics to guess branch probabilities if they are
6094 not provided by profiling feedback (@option{-fprofile-arcs}). These
6095 heuristics are based on the control flow graph. If some branch probabilities
6096 are specified by @samp{__builtin_expect}, then the heuristics will be
6097 used to guess branch probabilities for the rest of the control flow graph,
6098 taking the @samp{__builtin_expect} info into account. The interactions
6099 between the heuristics and @samp{__builtin_expect} can be complex, and in
6100 some cases, it may be useful to disable the heuristics so that the effects
6101 of @samp{__builtin_expect} are easier to understand.
6103 The default is @option{-fguess-branch-probability} at levels
6104 @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
6106 @item -freorder-blocks
6107 @opindex freorder-blocks
6108 Reorder basic blocks in the compiled function in order to reduce number of
6109 taken branches and improve code locality.
6111 Enabled at levels @option{-O2}, @option{-O3}.
6113 @item -freorder-blocks-and-partition
6114 @opindex freorder-blocks-and-partition
6115 In addition to reordering basic blocks in the compiled function, in order
6116 to reduce number of taken branches, partitions hot and cold basic blocks
6117 into separate sections of the assembly and .o files, to improve
6118 paging and cache locality performance.
6120 This optimization is automatically turned off in the presence of
6121 exception handling, for linkonce sections, for functions with a user-defined
6122 section attribute and on any architecture that does not support named
6125 @item -freorder-functions
6126 @opindex freorder-functions
6127 Reorder functions in the object file in order to
6128 improve code locality. This is implemented by using special
6129 subsections @code{.text.hot} for most frequently executed functions and
6130 @code{.text.unlikely} for unlikely executed functions. Reordering is done by
6131 the linker so object file format must support named sections and linker must
6132 place them in a reasonable way.
6134 Also profile feedback must be available in to make this option effective. See
6135 @option{-fprofile-arcs} for details.
6137 Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
6139 @item -fstrict-aliasing
6140 @opindex fstrict-aliasing
6141 Allows the compiler to assume the strictest aliasing rules applicable to
6142 the language being compiled. For C (and C++), this activates
6143 optimizations based on the type of expressions. In particular, an
6144 object of one type is assumed never to reside at the same address as an
6145 object of a different type, unless the types are almost the same. For
6146 example, an @code{unsigned int} can alias an @code{int}, but not a
6147 @code{void*} or a @code{double}. A character type may alias any other
6150 Pay special attention to code like this:
6163 The practice of reading from a different union member than the one most
6164 recently written to (called ``type-punning'') is common. Even with
6165 @option{-fstrict-aliasing}, type-punning is allowed, provided the memory
6166 is accessed through the union type. So, the code above will work as
6167 expected. However, this code might not:
6178 Enabled at levels @option{-O2}, @option{-O3}, @option{-Os}.
6180 @item -fstrict-overflow
6181 @opindex fstrict-overflow
6182 Allow the compiler to assume strict signed overflow rules, depending
6183 on the language being compiled. For C (and C++) this means that
6184 overflow when doing arithmetic with signed numbers is undefined, which
6185 means that the compiler may assume that it will not happen. This
6186 permits various optimizations. For example, the compiler will assume
6187 that an expression like @code{i + 10 > i} will always be true for
6188 signed @code{i}. This assumption is only valid if signed overflow is
6189 undefined, as the expression is false if @code{i + 10} overflows when
6190 using twos complement arithmetic. When this option is in effect any
6191 attempt to determine whether an operation on signed numbers will
6192 overflow must be written carefully to not actually involve overflow.
6194 See also the @option{-fwrapv} option. Using @option{-fwrapv} means
6195 that signed overflow is fully defined: it wraps. When
6196 @option{-fwrapv} is used, there is no difference between
6197 @option{-fstrict-overflow} and @option{-fno-strict-overflow}. With
6198 @option{-fwrapv} certain types of overflow are permitted. For
6199 example, if the compiler gets an overflow when doing arithmetic on
6200 constants, the overflowed value can still be used with
6201 @option{-fwrapv}, but not otherwise.
6203 The @option{-fstrict-overflow} option is enabled at levels
6204 @option{-O2}, @option{-O3}, @option{-Os}.
6206 @item -falign-functions
6207 @itemx -falign-functions=@var{n}
6208 @opindex falign-functions
6209 Align the start of functions to the next power-of-two greater than
6210 @var{n}, skipping up to @var{n} bytes. For instance,
6211 @option{-falign-functions=32} aligns functions to the next 32-byte
6212 boundary, but @option{-falign-functions=24} would align to the next
6213 32-byte boundary only if this can be done by skipping 23 bytes or less.
6215 @option{-fno-align-functions} and @option{-falign-functions=1} are
6216 equivalent and mean that functions will not be aligned.
6218 Some assemblers only support this flag when @var{n} is a power of two;
6219 in that case, it is rounded up.
6221 If @var{n} is not specified or is zero, use a machine-dependent default.
6223 Enabled at levels @option{-O2}, @option{-O3}.
6225 @item -falign-labels
6226 @itemx -falign-labels=@var{n}
6227 @opindex falign-labels
6228 Align all branch targets to a power-of-two boundary, skipping up to
6229 @var{n} bytes like @option{-falign-functions}. This option can easily
6230 make code slower, because it must insert dummy operations for when the
6231 branch target is reached in the usual flow of the code.
6233 @option{-fno-align-labels} and @option{-falign-labels=1} are
6234 equivalent and mean that labels will not be aligned.
6236 If @option{-falign-loops} or @option{-falign-jumps} are applicable and
6237 are greater than this value, then their values are used instead.
6239 If @var{n} is not specified or is zero, use a machine-dependent default
6240 which is very likely to be @samp{1}, meaning no alignment.
6242 Enabled at levels @option{-O2}, @option{-O3}.
6245 @itemx -falign-loops=@var{n}
6246 @opindex falign-loops
6247 Align loops to a power-of-two boundary, skipping up to @var{n} bytes
6248 like @option{-falign-functions}. The hope is that the loop will be
6249 executed many times, which will make up for any execution of the dummy
6252 @option{-fno-align-loops} and @option{-falign-loops=1} are
6253 equivalent and mean that loops will not be aligned.
6255 If @var{n} is not specified or is zero, use a machine-dependent default.
6257 Enabled at levels @option{-O2}, @option{-O3}.
6260 @itemx -falign-jumps=@var{n}
6261 @opindex falign-jumps
6262 Align branch targets to a power-of-two boundary, for branch targets
6263 where the targets can only be reached by jumping, skipping up to @var{n}
6264 bytes like @option{-falign-functions}. In this case, no dummy operations
6267 @option{-fno-align-jumps} and @option{-falign-jumps=1} are
6268 equivalent and mean that loops will not be aligned.
6270 If @var{n} is not specified or is zero, use a machine-dependent default.
6272 Enabled at levels @option{-O2}, @option{-O3}.
6274 @item -funit-at-a-time
6275 @opindex funit-at-a-time
6276 Parse the whole compilation unit before starting to produce code.
6277 This allows some extra optimizations to take place but consumes
6278 more memory (in general). There are some compatibility issues
6279 with @emph{unit-at-a-time} mode:
6282 enabling @emph{unit-at-a-time} mode may change the order
6283 in which functions, variables, and top-level @code{asm} statements
6284 are emitted, and will likely break code relying on some particular
6285 ordering. The majority of such top-level @code{asm} statements,
6286 though, can be replaced by @code{section} attributes. The
6287 @option{fno-toplevel-reorder} option may be used to keep the ordering
6288 used in the input file, at the cost of some optimizations.
6291 @emph{unit-at-a-time} mode removes unreferenced static variables
6292 and functions. This may result in undefined references
6293 when an @code{asm} statement refers directly to variables or functions
6294 that are otherwise unused. In that case either the variable/function
6295 shall be listed as an operand of the @code{asm} statement operand or,
6296 in the case of top-level @code{asm} statements the attribute @code{used}
6297 shall be used on the declaration.
6300 Static functions now can use non-standard passing conventions that
6301 may break @code{asm} statements calling functions directly. Again,
6302 attribute @code{used} will prevent this behavior.
6305 As a temporary workaround, @option{-fno-unit-at-a-time} can be used,
6306 but this scheme may not be supported by future releases of GCC@.
6308 Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
6310 @item -fno-toplevel-reorder
6311 @opindex fno-toplevel-reorder
6312 Do not reorder top-level functions, variables, and @code{asm}
6313 statements. Output them in the same order that they appear in the
6314 input file. When this option is used, unreferenced static variables
6315 will not be removed. This option is intended to support existing code
6316 which relies on a particular ordering. For new code, it is better to
6321 Constructs webs as commonly used for register allocation purposes and assign
6322 each web individual pseudo register. This allows the register allocation pass
6323 to operate on pseudos directly, but also strengthens several other optimization
6324 passes, such as CSE, loop optimizer and trivial dead code remover. It can,
6325 however, make debugging impossible, since variables will no longer stay in a
6328 Enabled by default with @option{-funroll-loops}.
6330 @item -fwhole-program
6331 @opindex fwhole-program
6332 Assume that the current compilation unit represents whole program being
6333 compiled. All public functions and variables with the exception of @code{main}
6334 and those merged by attribute @code{externally_visible} become static functions
6335 and in a affect gets more aggressively optimized by interprocedural optimizers.
6336 While this option is equivalent to proper use of @code{static} keyword for
6337 programs consisting of single file, in combination with option
6338 @option{--combine} this flag can be used to compile most of smaller scale C
6339 programs since the functions and variables become local for the whole combined
6340 compilation unit, not for the single source file itself.
6342 This option is not supported for Fortran programs.
6344 @item -fcprop-registers
6345 @opindex fcprop-registers
6346 After register allocation and post-register allocation instruction splitting,
6347 we perform a copy-propagation pass to try to reduce scheduling dependencies
6348 and occasionally eliminate the copy.
6350 Enabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}.
6352 @item -fprofile-generate
6353 @opindex fprofile-generate
6355 Enable options usually used for instrumenting application to produce
6356 profile useful for later recompilation with profile feedback based
6357 optimization. You must use @option{-fprofile-generate} both when
6358 compiling and when linking your program.
6360 The following options are enabled: @code{-fprofile-arcs}, @code{-fprofile-values}, @code{-fvpt}.
6363 @opindex fprofile-use
6364 Enable profile feedback directed optimizations, and optimizations
6365 generally profitable only with profile feedback available.
6367 The following options are enabled: @code{-fbranch-probabilities}, @code{-fvpt},
6368 @code{-funroll-loops}, @code{-fpeel-loops}, @code{-ftracer}
6370 By default, GCC emits an error message if the feedback profiles do not
6371 match the source code. This error can be turned into a warning by using
6372 @option{-Wcoverage-mismatch}. Note this may result in poorly optimized
6376 The following options control compiler behavior regarding floating
6377 point arithmetic. These options trade off between speed and
6378 correctness. All must be specifically enabled.
6382 @opindex ffloat-store
6383 Do not store floating point variables in registers, and inhibit other
6384 options that might change whether a floating point value is taken from a
6387 @cindex floating point precision
6388 This option prevents undesirable excess precision on machines such as
6389 the 68000 where the floating registers (of the 68881) keep more
6390 precision than a @code{double} is supposed to have. Similarly for the
6391 x86 architecture. For most programs, the excess precision does only
6392 good, but a few programs rely on the precise definition of IEEE floating
6393 point. Use @option{-ffloat-store} for such programs, after modifying
6394 them to store all pertinent intermediate computations into variables.
6398 Sets @option{-fno-math-errno}, @option{-funsafe-math-optimizations},
6399 @option{-ffinite-math-only}, @option{-fno-rounding-math},
6400 @option{-fno-signaling-nans} and @option{-fcx-limited-range}.
6402 This option causes the preprocessor macro @code{__FAST_MATH__} to be defined.
6404 This option is not turned on by any @option{-O} option since
6405 it can result in incorrect output for programs which depend on
6406 an exact implementation of IEEE or ISO rules/specifications for
6407 math functions. It may, however, yield faster code for programs
6408 that do not require the guarantees of these specifications.
6410 @item -fno-math-errno
6411 @opindex fno-math-errno
6412 Do not set ERRNO after calling math functions that are executed
6413 with a single instruction, e.g., sqrt. A program that relies on
6414 IEEE exceptions for math error handling may want to use this flag
6415 for speed while maintaining IEEE arithmetic compatibility.
6417 This option is not turned on by any @option{-O} option since
6418 it can result in incorrect output for programs which depend on
6419 an exact implementation of IEEE or ISO rules/specifications for
6420 math functions. It may, however, yield faster code for programs
6421 that do not require the guarantees of these specifications.
6423 The default is @option{-fmath-errno}.
6425 On Darwin systems, the math library never sets @code{errno}. There is
6426 therefore no reason for the compiler to consider the possibility that
6427 it might, and @option{-fno-math-errno} is the default.
6429 @item -funsafe-math-optimizations
6430 @opindex funsafe-math-optimizations
6432 Allow optimizations for floating-point arithmetic that (a) assume
6433 that arguments and results are valid and (b) may violate IEEE or
6434 ANSI standards. When used at link-time, it may include libraries
6435 or startup files that change the default FPU control word or other
6436 similar optimizations.
6438 This option is not turned on by any @option{-O} option since
6439 it can result in incorrect output for programs which depend on
6440 an exact implementation of IEEE or ISO rules/specifications for
6441 math functions. It may, however, yield faster code for programs
6442 that do not require the guarantees of these specifications.
6443 Enables @option{-fno-signed-zeros}, @option{-fno-trapping-math},
6444 @option{-fassociative-math} and @option{-freciprocal-math}.
6446 The default is @option{-fno-unsafe-math-optimizations}.
6448 @item -fassociative-math
6449 @opindex fassociative-math
6451 Allow re-association of operands in series of floating-point operations.
6452 This violates the ISO C and C++ language standard by possibly changing
6453 computation result. NOTE: re-ordering may change the sign of zero as
6454 well as ignore NaNs and inhibit or create underflow or overflow (and
6455 thus cannot be used on a code which relies on rounding behavior like
6456 @code{(x + 2**52) - 2**52)}. May also reorder floating-point comparisons
6457 and thus may not be used when ordered comparisons are required.
6458 This option requires that both @option{-fno-signed-zeros} and
6459 @option{-fno-trapping-math} be in effect. Moreover, it doesn't make
6460 much sense with @option{-frounding-math}.
6462 The default is @option{-fno-associative-math}.
6464 @item -freciprocal-math
6465 @opindex freciprocal-math
6467 Allow the reciprocal of a value to be used instead of dividing by
6468 the value if this enables optimizations. For example @code{x / y}
6469 can be replaced with @code{x * (1/y)} which is useful if @code{(1/y)}
6470 is subject to common subexpression elimination. Note that this loses
6471 precision and increases the number of flops operating on the value.
6473 The default is @option{-fno-reciprocal-math}.
6475 @item -ffinite-math-only
6476 @opindex ffinite-math-only
6477 Allow optimizations for floating-point arithmetic that assume
6478 that arguments and results are not NaNs or +-Infs.
6480 This option is not turned on by any @option{-O} option since
6481 it can result in incorrect output for programs which depend on
6482 an exact implementation of IEEE or ISO rules/specifications for
6483 math functions. It may, however, yield faster code for programs
6484 that do not require the guarantees of these specifications.
6486 The default is @option{-fno-finite-math-only}.
6488 @item -fno-signed-zeros
6489 @opindex fno-signed-zeros
6490 Allow optimizations for floating point arithmetic that ignore the
6491 signedness of zero. IEEE arithmetic specifies the behavior of
6492 distinct +0.0 and @minus{}0.0 values, which then prohibits simplification
6493 of expressions such as x+0.0 or 0.0*x (even with @option{-ffinite-math-only}).
6494 This option implies that the sign of a zero result isn't significant.
6496 The default is @option{-fsigned-zeros}.
6498 @item -fno-trapping-math
6499 @opindex fno-trapping-math
6500 Compile code assuming that floating-point operations cannot generate
6501 user-visible traps. These traps include division by zero, overflow,
6502 underflow, inexact result and invalid operation. This option requires
6503 that @option{-fno-signaling-nans} be in effect. Setting this option may
6504 allow faster code if one relies on ``non-stop'' IEEE arithmetic, for example.
6506 This option should never be turned on by any @option{-O} option since
6507 it can result in incorrect output for programs which depend on
6508 an exact implementation of IEEE or ISO rules/specifications for
6511 The default is @option{-ftrapping-math}.
6513 @item -frounding-math
6514 @opindex frounding-math
6515 Disable transformations and optimizations that assume default floating
6516 point rounding behavior. This is round-to-zero for all floating point
6517 to integer conversions, and round-to-nearest for all other arithmetic
6518 truncations. This option should be specified for programs that change
6519 the FP rounding mode dynamically, or that may be executed with a
6520 non-default rounding mode. This option disables constant folding of
6521 floating point expressions at compile-time (which may be affected by
6522 rounding mode) and arithmetic transformations that are unsafe in the
6523 presence of sign-dependent rounding modes.
6525 The default is @option{-fno-rounding-math}.
6527 This option is experimental and does not currently guarantee to
6528 disable all GCC optimizations that are affected by rounding mode.
6529 Future versions of GCC may provide finer control of this setting
6530 using C99's @code{FENV_ACCESS} pragma. This command line option
6531 will be used to specify the default state for @code{FENV_ACCESS}.
6533 @item -frtl-abstract-sequences
6534 @opindex frtl-abstract-sequences
6535 It is a size optimization method. This option is to find identical
6536 sequences of code, which can be turned into pseudo-procedures and
6537 then replace all occurrences with calls to the newly created
6538 subroutine. It is kind of an opposite of @option{-finline-functions}.
6539 This optimization runs at RTL level.
6541 @item -fsignaling-nans
6542 @opindex fsignaling-nans
6543 Compile code assuming that IEEE signaling NaNs may generate user-visible
6544 traps during floating-point operations. Setting this option disables
6545 optimizations that may change the number of exceptions visible with
6546 signaling NaNs. This option implies @option{-ftrapping-math}.
6548 This option causes the preprocessor macro @code{__SUPPORT_SNAN__} to
6551 The default is @option{-fno-signaling-nans}.
6553 This option is experimental and does not currently guarantee to
6554 disable all GCC optimizations that affect signaling NaN behavior.
6556 @item -fsingle-precision-constant
6557 @opindex fsingle-precision-constant
6558 Treat floating point constant as single precision constant instead of
6559 implicitly converting it to double precision constant.
6561 @item -fcx-limited-range
6562 @opindex fcx-limited-range
6563 When enabled, this option states that a range reduction step is not
6564 needed when performing complex division. Also, there is no checking
6565 whether the result of a complex multiplication or division is @code{NaN
6566 + I*NaN}, with an attempt to rescue the situation in that case. The
6567 default is @option{-fno-cx-limited-range}, but is enabled by
6568 @option{-ffast-math}.
6570 This option controls the default setting of the ISO C99
6571 @code{CX_LIMITED_RANGE} pragma. Nevertheless, the option applies to
6574 @item -fcx-fortran-rules
6575 @opindex fcx-fortran-rules
6576 Complex multiplication and division follow Fortran rules. Range
6577 reduction is done as part of complex division, but there is no checking
6578 whether the result of a complex multiplication or division is @code{NaN
6579 + I*NaN}, with an attempt to rescue the situation in that case.
6581 The default is @option{-fno-cx-fortran-rules}.
6585 The following options control optimizations that may improve
6586 performance, but are not enabled by any @option{-O} options. This
6587 section includes experimental options that may produce broken code.
6590 @item -fbranch-probabilities
6591 @opindex fbranch-probabilities
6592 After running a program compiled with @option{-fprofile-arcs}
6593 (@pxref{Debugging Options,, Options for Debugging Your Program or
6594 @command{gcc}}), you can compile it a second time using
6595 @option{-fbranch-probabilities}, to improve optimizations based on
6596 the number of times each branch was taken. When the program
6597 compiled with @option{-fprofile-arcs} exits it saves arc execution
6598 counts to a file called @file{@var{sourcename}.gcda} for each source
6599 file. The information in this data file is very dependent on the
6600 structure of the generated code, so you must use the same source code
6601 and the same optimization options for both compilations.
6603 With @option{-fbranch-probabilities}, GCC puts a
6604 @samp{REG_BR_PROB} note on each @samp{JUMP_INSN} and @samp{CALL_INSN}.
6605 These can be used to improve optimization. Currently, they are only
6606 used in one place: in @file{reorg.c}, instead of guessing which path a
6607 branch is mostly to take, the @samp{REG_BR_PROB} values are used to
6608 exactly determine which path is taken more often.
6610 @item -fprofile-values
6611 @opindex fprofile-values
6612 If combined with @option{-fprofile-arcs}, it adds code so that some
6613 data about values of expressions in the program is gathered.
6615 With @option{-fbranch-probabilities}, it reads back the data gathered
6616 from profiling values of expressions and adds @samp{REG_VALUE_PROFILE}
6617 notes to instructions for their later usage in optimizations.
6619 Enabled with @option{-fprofile-generate} and @option{-fprofile-use}.
6623 If combined with @option{-fprofile-arcs}, it instructs the compiler to add
6624 a code to gather information about values of expressions.
6626 With @option{-fbranch-probabilities}, it reads back the data gathered
6627 and actually performs the optimizations based on them.
6628 Currently the optimizations include specialization of division operation
6629 using the knowledge about the value of the denominator.
6631 @item -frename-registers
6632 @opindex frename-registers
6633 Attempt to avoid false dependencies in scheduled code by making use
6634 of registers left over after register allocation. This optimization
6635 will most benefit processors with lots of registers. Depending on the
6636 debug information format adopted by the target, however, it can
6637 make debugging impossible, since variables will no longer stay in
6638 a ``home register''.
6640 Enabled by default with @option{-funroll-loops}.
6644 Perform tail duplication to enlarge superblock size. This transformation
6645 simplifies the control flow of the function allowing other optimizations to do
6648 Enabled with @option{-fprofile-use}.
6650 @item -funroll-loops
6651 @opindex funroll-loops
6652 Unroll loops whose number of iterations can be determined at compile time or
6653 upon entry to the loop. @option{-funroll-loops} implies
6654 @option{-frerun-cse-after-loop}, @option{-fweb} and @option{-frename-registers}.
6655 It also turns on complete loop peeling (i.e.@: complete removal of loops with
6656 small constant number of iterations). This option makes code larger, and may
6657 or may not make it run faster.
6659 Enabled with @option{-fprofile-use}.
6661 @item -funroll-all-loops
6662 @opindex funroll-all-loops
6663 Unroll all loops, even if their number of iterations is uncertain when
6664 the loop is entered. This usually makes programs run more slowly.
6665 @option{-funroll-all-loops} implies the same options as
6666 @option{-funroll-loops}.
6669 @opindex fpeel-loops
6670 Peels the loops for that there is enough information that they do not
6671 roll much (from profile feedback). It also turns on complete loop peeling
6672 (i.e.@: complete removal of loops with small constant number of iterations).
6674 Enabled with @option{-fprofile-use}.
6676 @item -fmove-loop-invariants
6677 @opindex fmove-loop-invariants
6678 Enables the loop invariant motion pass in the RTL loop optimizer. Enabled
6679 at level @option{-O1}
6681 @item -funswitch-loops
6682 @opindex funswitch-loops
6683 Move branches with loop invariant conditions out of the loop, with duplicates
6684 of the loop on both branches (modified according to result of the condition).
6686 @item -ffunction-sections
6687 @itemx -fdata-sections
6688 @opindex ffunction-sections
6689 @opindex fdata-sections
6690 Place each function or data item into its own section in the output
6691 file if the target supports arbitrary sections. The name of the
6692 function or the name of the data item determines the section's name
6695 Use these options on systems where the linker can perform optimizations
6696 to improve locality of reference in the instruction space. Most systems
6697 using the ELF object format and SPARC processors running Solaris 2 have
6698 linkers with such optimizations. AIX may have these optimizations in
6701 Only use these options when there are significant benefits from doing
6702 so. When you specify these options, the assembler and linker will
6703 create larger object and executable files and will also be slower.
6704 You will not be able to use @code{gprof} on all systems if you
6705 specify this option and you may have problems with debugging if
6706 you specify both this option and @option{-g}.
6708 @item -fbranch-target-load-optimize
6709 @opindex fbranch-target-load-optimize
6710 Perform branch target register load optimization before prologue / epilogue
6712 The use of target registers can typically be exposed only during reload,
6713 thus hoisting loads out of loops and doing inter-block scheduling needs
6714 a separate optimization pass.
6716 @item -fbranch-target-load-optimize2
6717 @opindex fbranch-target-load-optimize2
6718 Perform branch target register load optimization after prologue / epilogue
6721 @item -fbtr-bb-exclusive
6722 @opindex fbtr-bb-exclusive
6723 When performing branch target register load optimization, don't reuse
6724 branch target registers in within any basic block.
6726 @item -fstack-protector
6727 @opindex fstack-protector
6728 Emit extra code to check for buffer overflows, such as stack smashing
6729 attacks. This is done by adding a guard variable to functions with
6730 vulnerable objects. This includes functions that call alloca, and
6731 functions with buffers larger than 8 bytes. The guards are initialized
6732 when a function is entered and then checked when the function exits.
6733 If a guard check fails, an error message is printed and the program exits.
6735 @item -fstack-protector-all
6736 @opindex fstack-protector-all
6737 Like @option{-fstack-protector} except that all functions are protected.
6739 @item -fsection-anchors
6740 @opindex fsection-anchors
6741 Try to reduce the number of symbolic address calculations by using
6742 shared ``anchor'' symbols to address nearby objects. This transformation
6743 can help to reduce the number of GOT entries and GOT accesses on some
6746 For example, the implementation of the following function @code{foo}:
6750 int foo (void) @{ return a + b + c; @}
6753 would usually calculate the addresses of all three variables, but if you
6754 compile it with @option{-fsection-anchors}, it will access the variables
6755 from a common anchor point instead. The effect is similar to the
6756 following pseudocode (which isn't valid C):
6761 register int *xr = &x;
6762 return xr[&a - &x] + xr[&b - &x] + xr[&c - &x];
6766 Not all targets support this option.
6768 @item --param @var{name}=@var{value}
6770 In some places, GCC uses various constants to control the amount of
6771 optimization that is done. For example, GCC will not inline functions
6772 that contain more that a certain number of instructions. You can
6773 control some of these constants on the command-line using the
6774 @option{--param} option.
6776 The names of specific parameters, and the meaning of the values, are
6777 tied to the internals of the compiler, and are subject to change
6778 without notice in future releases.
6780 In each case, the @var{value} is an integer. The allowable choices for
6781 @var{name} are given in the following table:
6784 @item salias-max-implicit-fields
6785 The maximum number of fields in a variable without direct
6786 structure accesses for which structure aliasing will consider trying
6787 to track each field. The default is 5
6789 @item salias-max-array-elements
6790 The maximum number of elements an array can have and its elements
6791 still be tracked individually by structure aliasing. The default is 4
6793 @item sra-max-structure-size
6794 The maximum structure size, in bytes, at which the scalar replacement
6795 of aggregates (SRA) optimization will perform block copies. The
6796 default value, 0, implies that GCC will select the most appropriate
6799 @item sra-field-structure-ratio
6800 The threshold ratio (as a percentage) between instantiated fields and
6801 the complete structure size. We say that if the ratio of the number
6802 of bytes in instantiated fields to the number of bytes in the complete
6803 structure exceeds this parameter, then block copies are not used. The
6806 @item struct-reorg-cold-struct-ratio
6807 The threshold ratio (as a percentage) between a structure frequency
6808 and the frequency of the hottest structure in the program. This parameter
6809 is used by struct-reorg optimization enabled by @option{-fipa-struct-reorg}.
6810 We say that if the ratio of a structure frequency, calculated by profiling,
6811 to the hottest structure frequency in the program is less than this
6812 parameter, then structure reorganization is not applied to this structure.
6815 @item max-crossjump-edges
6816 The maximum number of incoming edges to consider for crossjumping.
6817 The algorithm used by @option{-fcrossjumping} is @math{O(N^2)} in
6818 the number of edges incoming to each block. Increasing values mean
6819 more aggressive optimization, making the compile time increase with
6820 probably small improvement in executable size.
6822 @item min-crossjump-insns
6823 The minimum number of instructions which must be matched at the end
6824 of two blocks before crossjumping will be performed on them. This
6825 value is ignored in the case where all instructions in the block being
6826 crossjumped from are matched. The default value is 5.
6828 @item max-grow-copy-bb-insns
6829 The maximum code size expansion factor when copying basic blocks
6830 instead of jumping. The expansion is relative to a jump instruction.
6831 The default value is 8.
6833 @item max-goto-duplication-insns
6834 The maximum number of instructions to duplicate to a block that jumps
6835 to a computed goto. To avoid @math{O(N^2)} behavior in a number of
6836 passes, GCC factors computed gotos early in the compilation process,
6837 and unfactors them as late as possible. Only computed jumps at the
6838 end of a basic blocks with no more than max-goto-duplication-insns are
6839 unfactored. The default value is 8.
6841 @item max-delay-slot-insn-search
6842 The maximum number of instructions to consider when looking for an
6843 instruction to fill a delay slot. If more than this arbitrary number of
6844 instructions is searched, the time savings from filling the delay slot
6845 will be minimal so stop searching. Increasing values mean more
6846 aggressive optimization, making the compile time increase with probably
6847 small improvement in executable run time.
6849 @item max-delay-slot-live-search
6850 When trying to fill delay slots, the maximum number of instructions to
6851 consider when searching for a block with valid live register
6852 information. Increasing this arbitrarily chosen value means more
6853 aggressive optimization, increasing the compile time. This parameter
6854 should be removed when the delay slot code is rewritten to maintain the
6857 @item max-gcse-memory
6858 The approximate maximum amount of memory that will be allocated in
6859 order to perform the global common subexpression elimination
6860 optimization. If more memory than specified is required, the
6861 optimization will not be done.
6863 @item max-gcse-passes
6864 The maximum number of passes of GCSE to run. The default is 1.
6866 @item max-pending-list-length
6867 The maximum number of pending dependencies scheduling will allow
6868 before flushing the current state and starting over. Large functions
6869 with few branches or calls can create excessively large lists which
6870 needlessly consume memory and resources.
6872 @item max-inline-insns-single
6873 Several parameters control the tree inliner used in gcc.
6874 This number sets the maximum number of instructions (counted in GCC's
6875 internal representation) in a single function that the tree inliner
6876 will consider for inlining. This only affects functions declared
6877 inline and methods implemented in a class declaration (C++).
6878 The default value is 450.
6880 @item max-inline-insns-auto
6881 When you use @option{-finline-functions} (included in @option{-O3}),
6882 a lot of functions that would otherwise not be considered for inlining
6883 by the compiler will be investigated. To those functions, a different
6884 (more restrictive) limit compared to functions declared inline can
6886 The default value is 90.
6888 @item large-function-insns
6889 The limit specifying really large functions. For functions larger than this
6890 limit after inlining inlining is constrained by
6891 @option{--param large-function-growth}. This parameter is useful primarily
6892 to avoid extreme compilation time caused by non-linear algorithms used by the
6894 This parameter is ignored when @option{-funit-at-a-time} is not used.
6895 The default value is 2700.
6897 @item large-function-growth
6898 Specifies maximal growth of large function caused by inlining in percents.
6899 This parameter is ignored when @option{-funit-at-a-time} is not used.
6900 The default value is 100 which limits large function growth to 2.0 times
6903 @item large-unit-insns
6904 The limit specifying large translation unit. Growth caused by inlining of
6905 units larger than this limit is limited by @option{--param inline-unit-growth}.
6906 For small units this might be too tight (consider unit consisting of function A
6907 that is inline and B that just calls A three time. If B is small relative to
6908 A, the growth of unit is 300\% and yet such inlining is very sane. For very
6909 large units consisting of small inlineable functions however the overall unit
6910 growth limit is needed to avoid exponential explosion of code size. Thus for
6911 smaller units, the size is increased to @option{--param large-unit-insns}
6912 before applying @option{--param inline-unit-growth}. The default is 10000
6914 @item inline-unit-growth
6915 Specifies maximal overall growth of the compilation unit caused by inlining.
6916 This parameter is ignored when @option{-funit-at-a-time} is not used.
6917 The default value is 30 which limits unit growth to 1.3 times the original
6920 @item large-stack-frame
6921 The limit specifying large stack frames. While inlining the algorithm is trying
6922 to not grow past this limit too much. Default value is 256 bytes.
6924 @item large-stack-frame-growth
6925 Specifies maximal growth of large stack frames caused by inlining in percents.
6926 The default value is 1000 which limits large stack frame growth to 11 times
6929 @item max-inline-insns-recursive
6930 @itemx max-inline-insns-recursive-auto
6931 Specifies maximum number of instructions out-of-line copy of self recursive inline
6932 function can grow into by performing recursive inlining.
6934 For functions declared inline @option{--param max-inline-insns-recursive} is
6935 taken into account. For function not declared inline, recursive inlining
6936 happens only when @option{-finline-functions} (included in @option{-O3}) is
6937 enabled and @option{--param max-inline-insns-recursive-auto} is used. The
6938 default value is 450.
6940 @item max-inline-recursive-depth
6941 @itemx max-inline-recursive-depth-auto
6942 Specifies maximum recursion depth used by the recursive inlining.
6944 For functions declared inline @option{--param max-inline-recursive-depth} is
6945 taken into account. For function not declared inline, recursive inlining
6946 happens only when @option{-finline-functions} (included in @option{-O3}) is
6947 enabled and @option{--param max-inline-recursive-depth-auto} is used. The
6950 @item min-inline-recursive-probability
6951 Recursive inlining is profitable only for function having deep recursion
6952 in average and can hurt for function having little recursion depth by
6953 increasing the prologue size or complexity of function body to other
6956 When profile feedback is available (see @option{-fprofile-generate}) the actual
6957 recursion depth can be guessed from probability that function will recurse via
6958 given call expression. This parameter limits inlining only to call expression
6959 whose probability exceeds given threshold (in percents). The default value is
6962 @item inline-call-cost
6963 Specify cost of call instruction relative to simple arithmetics operations
6964 (having cost of 1). Increasing this cost disqualifies inlining of non-leaf
6965 functions and at the same time increases size of leaf function that is believed to
6966 reduce function size by being inlined. In effect it increases amount of
6967 inlining for code having large abstraction penalty (many functions that just
6968 pass the arguments to other functions) and decrease inlining for code with low
6969 abstraction penalty. The default value is 12.
6971 @item min-vect-loop-bound
6972 The minimum number of iterations under which a loop will not get vectorized
6973 when @option{-ftree-vectorize} is used. The number of iterations after
6974 vectorization needs to be greater than the value specified by this option
6975 to allow vectorization. The default value is 0.
6977 @item max-unrolled-insns
6978 The maximum number of instructions that a loop should have if that loop
6979 is unrolled, and if the loop is unrolled, it determines how many times
6980 the loop code is unrolled.
6982 @item max-average-unrolled-insns
6983 The maximum number of instructions biased by probabilities of their execution
6984 that a loop should have if that loop is unrolled, and if the loop is unrolled,
6985 it determines how many times the loop code is unrolled.
6987 @item max-unroll-times
6988 The maximum number of unrollings of a single loop.
6990 @item max-peeled-insns
6991 The maximum number of instructions that a loop should have if that loop
6992 is peeled, and if the loop is peeled, it determines how many times
6993 the loop code is peeled.
6995 @item max-peel-times
6996 The maximum number of peelings of a single loop.
6998 @item max-completely-peeled-insns
6999 The maximum number of insns of a completely peeled loop.
7001 @item max-completely-peel-times
7002 The maximum number of iterations of a loop to be suitable for complete peeling.
7004 @item max-unswitch-insns
7005 The maximum number of insns of an unswitched loop.
7007 @item max-unswitch-level
7008 The maximum number of branches unswitched in a single loop.
7011 The minimum cost of an expensive expression in the loop invariant motion.
7013 @item iv-consider-all-candidates-bound
7014 Bound on number of candidates for induction variables below that
7015 all candidates are considered for each use in induction variable
7016 optimizations. Only the most relevant candidates are considered
7017 if there are more candidates, to avoid quadratic time complexity.
7019 @item iv-max-considered-uses
7020 The induction variable optimizations give up on loops that contain more
7021 induction variable uses.
7023 @item iv-always-prune-cand-set-bound
7024 If number of candidates in the set is smaller than this value,
7025 we always try to remove unnecessary ivs from the set during its
7026 optimization when a new iv is added to the set.
7028 @item scev-max-expr-size
7029 Bound on size of expressions used in the scalar evolutions analyzer.
7030 Large expressions slow the analyzer.
7032 @item omega-max-vars
7033 The maximum number of variables in an Omega constraint system.
7034 The default value is 128.
7036 @item omega-max-geqs
7037 The maximum number of inequalities in an Omega constraint system.
7038 The default value is 256.
7041 The maximum number of equalities in an Omega constraint system.
7042 The default value is 128.
7044 @item omega-max-wild-cards
7045 The maximum number of wildcard variables that the Omega solver will
7046 be able to insert. The default value is 18.
7048 @item omega-hash-table-size
7049 The size of the hash table in the Omega solver. The default value is
7052 @item omega-max-keys
7053 The maximal number of keys used by the Omega solver. The default
7056 @item omega-eliminate-redundant-constraints
7057 When set to 1, use expensive methods to eliminate all redundant
7058 constraints. The default value is 0.
7060 @item vect-max-version-for-alignment-checks
7061 The maximum number of runtime checks that can be performed when
7062 doing loop versioning for alignment in the vectorizer. See option
7063 ftree-vect-loop-version for more information.
7065 @item vect-max-version-for-alias-checks
7066 The maximum number of runtime checks that can be performed when
7067 doing loop versioning for alias in the vectorizer. See option
7068 ftree-vect-loop-version for more information.
7070 @item max-iterations-to-track
7072 The maximum number of iterations of a loop the brute force algorithm
7073 for analysis of # of iterations of the loop tries to evaluate.
7075 @item hot-bb-count-fraction
7076 Select fraction of the maximal count of repetitions of basic block in program
7077 given basic block needs to have to be considered hot.
7079 @item hot-bb-frequency-fraction
7080 Select fraction of the maximal frequency of executions of basic block in
7081 function given basic block needs to have to be considered hot
7083 @item max-predicted-iterations
7084 The maximum number of loop iterations we predict statically. This is useful
7085 in cases where function contain single loop with known bound and other loop
7086 with unknown. We predict the known number of iterations correctly, while
7087 the unknown number of iterations average to roughly 10. This means that the
7088 loop without bounds would appear artificially cold relative to the other one.
7090 @item align-threshold
7092 Select fraction of the maximal frequency of executions of basic block in
7093 function given basic block will get aligned.
7095 @item align-loop-iterations
7097 A loop expected to iterate at lest the selected number of iterations will get
7100 @item tracer-dynamic-coverage
7101 @itemx tracer-dynamic-coverage-feedback
7103 This value is used to limit superblock formation once the given percentage of
7104 executed instructions is covered. This limits unnecessary code size
7107 The @option{tracer-dynamic-coverage-feedback} is used only when profile
7108 feedback is available. The real profiles (as opposed to statically estimated
7109 ones) are much less balanced allowing the threshold to be larger value.
7111 @item tracer-max-code-growth
7112 Stop tail duplication once code growth has reached given percentage. This is
7113 rather hokey argument, as most of the duplicates will be eliminated later in
7114 cross jumping, so it may be set to much higher values than is the desired code
7117 @item tracer-min-branch-ratio
7119 Stop reverse growth when the reverse probability of best edge is less than this
7120 threshold (in percent).
7122 @item tracer-min-branch-ratio
7123 @itemx tracer-min-branch-ratio-feedback
7125 Stop forward growth if the best edge do have probability lower than this
7128 Similarly to @option{tracer-dynamic-coverage} two values are present, one for
7129 compilation for profile feedback and one for compilation without. The value
7130 for compilation with profile feedback needs to be more conservative (higher) in
7131 order to make tracer effective.
7133 @item max-cse-path-length
7135 Maximum number of basic blocks on path that cse considers. The default is 10.
7138 The maximum instructions CSE process before flushing. The default is 1000.
7140 @item max-aliased-vops
7142 Maximum number of virtual operands per function allowed to represent
7143 aliases before triggering the alias partitioning heuristic. Alias
7144 partitioning reduces compile times and memory consumption needed for
7145 aliasing at the expense of precision loss in alias information. The
7146 default value for this parameter is 100 for -O1, 500 for -O2 and 1000
7149 Notice that if a function contains more memory statements than the
7150 value of this parameter, it is not really possible to achieve this
7151 reduction. In this case, the compiler will use the number of memory
7152 statements as the value for @option{max-aliased-vops}.
7154 @item avg-aliased-vops
7156 Average number of virtual operands per statement allowed to represent
7157 aliases before triggering the alias partitioning heuristic. This
7158 works in conjunction with @option{max-aliased-vops}. If a function
7159 contains more than @option{max-aliased-vops} virtual operators, then
7160 memory symbols will be grouped into memory partitions until either the
7161 total number of virtual operators is below @option{max-aliased-vops}
7162 or the average number of virtual operators per memory statement is
7163 below @option{avg-aliased-vops}. The default value for this parameter
7164 is 1 for -O1 and -O2, and 3 for -O3.
7166 @item ggc-min-expand
7168 GCC uses a garbage collector to manage its own memory allocation. This
7169 parameter specifies the minimum percentage by which the garbage
7170 collector's heap should be allowed to expand between collections.
7171 Tuning this may improve compilation speed; it has no effect on code
7174 The default is 30% + 70% * (RAM/1GB) with an upper bound of 100% when
7175 RAM >= 1GB@. If @code{getrlimit} is available, the notion of "RAM" is
7176 the smallest of actual RAM and @code{RLIMIT_DATA} or @code{RLIMIT_AS}. If
7177 GCC is not able to calculate RAM on a particular platform, the lower
7178 bound of 30% is used. Setting this parameter and
7179 @option{ggc-min-heapsize} to zero causes a full collection to occur at
7180 every opportunity. This is extremely slow, but can be useful for
7183 @item ggc-min-heapsize
7185 Minimum size of the garbage collector's heap before it begins bothering
7186 to collect garbage. The first collection occurs after the heap expands
7187 by @option{ggc-min-expand}% beyond @option{ggc-min-heapsize}. Again,
7188 tuning this may improve compilation speed, and has no effect on code
7191 The default is the smaller of RAM/8, RLIMIT_RSS, or a limit which
7192 tries to ensure that RLIMIT_DATA or RLIMIT_AS are not exceeded, but
7193 with a lower bound of 4096 (four megabytes) and an upper bound of
7194 131072 (128 megabytes). If GCC is not able to calculate RAM on a
7195 particular platform, the lower bound is used. Setting this parameter
7196 very large effectively disables garbage collection. Setting this
7197 parameter and @option{ggc-min-expand} to zero causes a full collection
7198 to occur at every opportunity.
7200 @item max-reload-search-insns
7201 The maximum number of instruction reload should look backward for equivalent
7202 register. Increasing values mean more aggressive optimization, making the
7203 compile time increase with probably slightly better performance. The default
7206 @item max-cselib-memory-locations
7207 The maximum number of memory locations cselib should take into account.
7208 Increasing values mean more aggressive optimization, making the compile time
7209 increase with probably slightly better performance. The default value is 500.
7211 @item max-flow-memory-locations
7212 Similar as @option{max-cselib-memory-locations} but for dataflow liveness.
7213 The default value is 100.
7215 @item reorder-blocks-duplicate
7216 @itemx reorder-blocks-duplicate-feedback
7218 Used by basic block reordering pass to decide whether to use unconditional
7219 branch or duplicate the code on its destination. Code is duplicated when its
7220 estimated size is smaller than this value multiplied by the estimated size of
7221 unconditional jump in the hot spots of the program.
7223 The @option{reorder-block-duplicate-feedback} is used only when profile
7224 feedback is available and may be set to higher values than
7225 @option{reorder-block-duplicate} since information about the hot spots is more
7228 @item max-sched-ready-insns
7229 The maximum number of instructions ready to be issued the scheduler should
7230 consider at any given time during the first scheduling pass. Increasing
7231 values mean more thorough searches, making the compilation time increase
7232 with probably little benefit. The default value is 100.
7234 @item max-sched-region-blocks
7235 The maximum number of blocks in a region to be considered for
7236 interblock scheduling. The default value is 10.
7238 @item max-sched-region-insns
7239 The maximum number of insns in a region to be considered for
7240 interblock scheduling. The default value is 100.
7243 The minimum probability (in percents) of reaching a source block
7244 for interblock speculative scheduling. The default value is 40.
7246 @item max-sched-extend-regions-iters
7247 The maximum number of iterations through CFG to extend regions.
7248 0 - disable region extension,
7249 N - do at most N iterations.
7250 The default value is 0.
7252 @item max-sched-insn-conflict-delay
7253 The maximum conflict delay for an insn to be considered for speculative motion.
7254 The default value is 3.
7256 @item sched-spec-prob-cutoff
7257 The minimal probability of speculation success (in percents), so that
7258 speculative insn will be scheduled.
7259 The default value is 40.
7261 @item max-last-value-rtl
7263 The maximum size measured as number of RTLs that can be recorded in an expression
7264 in combiner for a pseudo register as last known value of that register. The default
7267 @item integer-share-limit
7268 Small integer constants can use a shared data structure, reducing the
7269 compiler's memory usage and increasing its speed. This sets the maximum
7270 value of a shared integer constant. The default value is 256.
7272 @item min-virtual-mappings
7273 Specifies the minimum number of virtual mappings in the incremental
7274 SSA updater that should be registered to trigger the virtual mappings
7275 heuristic defined by virtual-mappings-ratio. The default value is
7278 @item virtual-mappings-ratio
7279 If the number of virtual mappings is virtual-mappings-ratio bigger
7280 than the number of virtual symbols to be updated, then the incremental
7281 SSA updater switches to a full update for those symbols. The default
7284 @item ssp-buffer-size
7285 The minimum size of buffers (i.e.@: arrays) that will receive stack smashing
7286 protection when @option{-fstack-protection} is used.
7288 @item max-jump-thread-duplication-stmts
7289 Maximum number of statements allowed in a block that needs to be
7290 duplicated when threading jumps.
7292 @item max-fields-for-field-sensitive
7293 Maximum number of fields in a structure we will treat in
7294 a field sensitive manner during pointer analysis.
7296 @item prefetch-latency
7297 Estimate on average number of instructions that are executed before
7298 prefetch finishes. The distance we prefetch ahead is proportional
7299 to this constant. Increasing this number may also lead to less
7300 streams being prefetched (see @option{simultaneous-prefetches}).
7302 @item simultaneous-prefetches
7303 Maximum number of prefetches that can run at the same time.
7305 @item l1-cache-line-size
7306 The size of cache line in L1 cache, in bytes.
7309 The size of L1 cache, in kilobytes.
7312 The size of L2 cache, in kilobytes.
7314 @item use-canonical-types
7315 Whether the compiler should use the ``canonical'' type system. By
7316 default, this should always be 1, which uses a more efficient internal
7317 mechanism for comparing types in C++ and Objective-C++. However, if
7318 bugs in the canonical type system are causing compilation failures,
7319 set this value to 0 to disable canonical types.
7321 @item max-partial-antic-length
7322 Maximum length of the partial antic set computed during the tree
7323 partial redundancy elimination optimization (@option{-ftree-pre}) when
7324 optimizing at @option{-O3} and above. For some sorts of source code
7325 the enhanced partial redundancy elimination optimization can run away,
7326 consuming all of the memory available on the host machine. This
7327 parameter sets a limit on the length of the sets that are computed,
7328 which prevents the runaway behaviour. Setting a value of 0 for
7329 this paramter will allow an unlimited set length.
7331 @item sccvn-max-scc-size
7332 Maximum size of a strongly connected component (SCC) during SCCVN
7333 processing. If this limit is hit, SCCVN processing for the whole
7334 function will not be done and optimizations depending on it will
7335 be disabled. The default maximum SCC size is 10000.
7340 @node Preprocessor Options
7341 @section Options Controlling the Preprocessor
7342 @cindex preprocessor options
7343 @cindex options, preprocessor
7345 These options control the C preprocessor, which is run on each C source
7346 file before actual compilation.
7348 If you use the @option{-E} option, nothing is done except preprocessing.
7349 Some of these options make sense only together with @option{-E} because
7350 they cause the preprocessor output to be unsuitable for actual
7355 You can use @option{-Wp,@var{option}} to bypass the compiler driver
7356 and pass @var{option} directly through to the preprocessor. If
7357 @var{option} contains commas, it is split into multiple options at the
7358 commas. However, many options are modified, translated or interpreted
7359 by the compiler driver before being passed to the preprocessor, and
7360 @option{-Wp} forcibly bypasses this phase. The preprocessor's direct
7361 interface is undocumented and subject to change, so whenever possible
7362 you should avoid using @option{-Wp} and let the driver handle the
7365 @item -Xpreprocessor @var{option}
7366 @opindex preprocessor
7367 Pass @var{option} as an option to the preprocessor. You can use this to
7368 supply system-specific preprocessor options which GCC does not know how to
7371 If you want to pass an option that takes an argument, you must use
7372 @option{-Xpreprocessor} twice, once for the option and once for the argument.
7375 @include cppopts.texi
7377 @node Assembler Options
7378 @section Passing Options to the Assembler
7380 @c prevent bad page break with this line
7381 You can pass options to the assembler.
7384 @item -Wa,@var{option}
7386 Pass @var{option} as an option to the assembler. If @var{option}
7387 contains commas, it is split into multiple options at the commas.
7389 @item -Xassembler @var{option}
7391 Pass @var{option} as an option to the assembler. You can use this to
7392 supply system-specific assembler options which GCC does not know how to
7395 If you want to pass an option that takes an argument, you must use
7396 @option{-Xassembler} twice, once for the option and once for the argument.
7401 @section Options for Linking
7402 @cindex link options
7403 @cindex options, linking
7405 These options come into play when the compiler links object files into
7406 an executable output file. They are meaningless if the compiler is
7407 not doing a link step.
7411 @item @var{object-file-name}
7412 A file name that does not end in a special recognized suffix is
7413 considered to name an object file or library. (Object files are
7414 distinguished from libraries by the linker according to the file
7415 contents.) If linking is done, these object files are used as input
7424 If any of these options is used, then the linker is not run, and
7425 object file names should not be used as arguments. @xref{Overall
7429 @item -l@var{library}
7430 @itemx -l @var{library}
7432 Search the library named @var{library} when linking. (The second
7433 alternative with the library as a separate argument is only for
7434 POSIX compliance and is not recommended.)
7436 It makes a difference where in the command you write this option; the
7437 linker searches and processes libraries and object files in the order they
7438 are specified. Thus, @samp{foo.o -lz bar.o} searches library @samp{z}
7439 after file @file{foo.o} but before @file{bar.o}. If @file{bar.o} refers
7440 to functions in @samp{z}, those functions may not be loaded.
7442 The linker searches a standard list of directories for the library,
7443 which is actually a file named @file{lib@var{library}.a}. The linker
7444 then uses this file as if it had been specified precisely by name.
7446 The directories searched include several standard system directories
7447 plus any that you specify with @option{-L}.
7449 Normally the files found this way are library files---archive files
7450 whose members are object files. The linker handles an archive file by
7451 scanning through it for members which define symbols that have so far
7452 been referenced but not defined. But if the file that is found is an
7453 ordinary object file, it is linked in the usual fashion. The only
7454 difference between using an @option{-l} option and specifying a file name
7455 is that @option{-l} surrounds @var{library} with @samp{lib} and @samp{.a}
7456 and searches several directories.
7460 You need this special case of the @option{-l} option in order to
7461 link an Objective-C or Objective-C++ program.
7464 @opindex nostartfiles
7465 Do not use the standard system startup files when linking.
7466 The standard system libraries are used normally, unless @option{-nostdlib}
7467 or @option{-nodefaultlibs} is used.
7469 @item -nodefaultlibs
7470 @opindex nodefaultlibs
7471 Do not use the standard system libraries when linking.
7472 Only the libraries you specify will be passed to the linker.
7473 The standard startup files are used normally, unless @option{-nostartfiles}
7474 is used. The compiler may generate calls to @code{memcmp},
7475 @code{memset}, @code{memcpy} and @code{memmove}.
7476 These entries are usually resolved by entries in
7477 libc. These entry points should be supplied through some other
7478 mechanism when this option is specified.
7482 Do not use the standard system startup files or libraries when linking.
7483 No startup files and only the libraries you specify will be passed to
7484 the linker. The compiler may generate calls to @code{memcmp}, @code{memset},
7485 @code{memcpy} and @code{memmove}.
7486 These entries are usually resolved by entries in
7487 libc. These entry points should be supplied through some other
7488 mechanism when this option is specified.
7490 @cindex @option{-lgcc}, use with @option{-nostdlib}
7491 @cindex @option{-nostdlib} and unresolved references
7492 @cindex unresolved references and @option{-nostdlib}
7493 @cindex @option{-lgcc}, use with @option{-nodefaultlibs}
7494 @cindex @option{-nodefaultlibs} and unresolved references
7495 @cindex unresolved references and @option{-nodefaultlibs}
7496 One of the standard libraries bypassed by @option{-nostdlib} and
7497 @option{-nodefaultlibs} is @file{libgcc.a}, a library of internal subroutines
7498 that GCC uses to overcome shortcomings of particular machines, or special
7499 needs for some languages.
7500 (@xref{Interface,,Interfacing to GCC Output,gccint,GNU Compiler
7501 Collection (GCC) Internals},
7502 for more discussion of @file{libgcc.a}.)
7503 In most cases, you need @file{libgcc.a} even when you want to avoid
7504 other standard libraries. In other words, when you specify @option{-nostdlib}
7505 or @option{-nodefaultlibs} you should usually specify @option{-lgcc} as well.
7506 This ensures that you have no unresolved references to internal GCC
7507 library subroutines. (For example, @samp{__main}, used to ensure C++
7508 constructors will be called; @pxref{Collect2,,@code{collect2}, gccint,
7509 GNU Compiler Collection (GCC) Internals}.)
7513 Produce a position independent executable on targets which support it.
7514 For predictable results, you must also specify the same set of options
7515 that were used to generate code (@option{-fpie}, @option{-fPIE},
7516 or model suboptions) when you specify this option.
7520 Pass the flag @option{-export-dynamic} to the ELF linker, on targets
7521 that support it. This instructs the linker to add all symbols, not
7522 only used ones, to the dynamic symbol table. This option is needed
7523 for some uses of @code{dlopen} or to allow obtaining backtraces
7524 from within a program.
7528 Remove all symbol table and relocation information from the executable.
7532 On systems that support dynamic linking, this prevents linking with the shared
7533 libraries. On other systems, this option has no effect.
7537 Produce a shared object which can then be linked with other objects to
7538 form an executable. Not all systems support this option. For predictable
7539 results, you must also specify the same set of options that were used to
7540 generate code (@option{-fpic}, @option{-fPIC}, or model suboptions)
7541 when you specify this option.@footnote{On some systems, @samp{gcc -shared}
7542 needs to build supplementary stub code for constructors to work. On
7543 multi-libbed systems, @samp{gcc -shared} must select the correct support
7544 libraries to link against. Failing to supply the correct flags may lead
7545 to subtle defects. Supplying them in cases where they are not necessary
7548 @item -shared-libgcc
7549 @itemx -static-libgcc
7550 @opindex shared-libgcc
7551 @opindex static-libgcc
7552 On systems that provide @file{libgcc} as a shared library, these options
7553 force the use of either the shared or static version respectively.
7554 If no shared version of @file{libgcc} was built when the compiler was
7555 configured, these options have no effect.
7557 There are several situations in which an application should use the
7558 shared @file{libgcc} instead of the static version. The most common
7559 of these is when the application wishes to throw and catch exceptions
7560 across different shared libraries. In that case, each of the libraries
7561 as well as the application itself should use the shared @file{libgcc}.
7563 Therefore, the G++ and GCJ drivers automatically add
7564 @option{-shared-libgcc} whenever you build a shared library or a main
7565 executable, because C++ and Java programs typically use exceptions, so
7566 this is the right thing to do.
7568 If, instead, you use the GCC driver to create shared libraries, you may
7569 find that they will not always be linked with the shared @file{libgcc}.
7570 If GCC finds, at its configuration time, that you have a non-GNU linker
7571 or a GNU linker that does not support option @option{--eh-frame-hdr},
7572 it will link the shared version of @file{libgcc} into shared libraries
7573 by default. Otherwise, it will take advantage of the linker and optimize
7574 away the linking with the shared version of @file{libgcc}, linking with
7575 the static version of libgcc by default. This allows exceptions to
7576 propagate through such shared libraries, without incurring relocation
7577 costs at library load time.
7579 However, if a library or main executable is supposed to throw or catch
7580 exceptions, you must link it using the G++ or GCJ driver, as appropriate
7581 for the languages used in the program, or using the option
7582 @option{-shared-libgcc}, such that it is linked with the shared
7587 Bind references to global symbols when building a shared object. Warn
7588 about any unresolved references (unless overridden by the link editor
7589 option @samp{-Xlinker -z -Xlinker defs}). Only a few systems support
7592 @item -Xlinker @var{option}
7594 Pass @var{option} as an option to the linker. You can use this to
7595 supply system-specific linker options which GCC does not know how to
7598 If you want to pass an option that takes an argument, you must use
7599 @option{-Xlinker} twice, once for the option and once for the argument.
7600 For example, to pass @option{-assert definitions}, you must write
7601 @samp{-Xlinker -assert -Xlinker definitions}. It does not work to write
7602 @option{-Xlinker "-assert definitions"}, because this passes the entire
7603 string as a single argument, which is not what the linker expects.
7605 @item -Wl,@var{option}
7607 Pass @var{option} as an option to the linker. If @var{option} contains
7608 commas, it is split into multiple options at the commas.
7610 @item -u @var{symbol}
7612 Pretend the symbol @var{symbol} is undefined, to force linking of
7613 library modules to define it. You can use @option{-u} multiple times with
7614 different symbols to force loading of additional library modules.
7617 @node Directory Options
7618 @section Options for Directory Search
7619 @cindex directory options
7620 @cindex options, directory search
7623 These options specify directories to search for header files, for
7624 libraries and for parts of the compiler:
7629 Add the directory @var{dir} to the head of the list of directories to be
7630 searched for header files. This can be used to override a system header
7631 file, substituting your own version, since these directories are
7632 searched before the system header file directories. However, you should
7633 not use this option to add directories that contain vendor-supplied
7634 system header files (use @option{-isystem} for that). If you use more than
7635 one @option{-I} option, the directories are scanned in left-to-right
7636 order; the standard system directories come after.
7638 If a standard system include directory, or a directory specified with
7639 @option{-isystem}, is also specified with @option{-I}, the @option{-I}
7640 option will be ignored. The directory will still be searched but as a
7641 system directory at its normal position in the system include chain.
7642 This is to ensure that GCC's procedure to fix buggy system headers and
7643 the ordering for the include_next directive are not inadvertently changed.
7644 If you really need to change the search order for system directories,
7645 use the @option{-nostdinc} and/or @option{-isystem} options.
7647 @item -iquote@var{dir}
7649 Add the directory @var{dir} to the head of the list of directories to
7650 be searched for header files only for the case of @samp{#include
7651 "@var{file}"}; they are not searched for @samp{#include <@var{file}>},
7652 otherwise just like @option{-I}.
7656 Add directory @var{dir} to the list of directories to be searched
7659 @item -B@var{prefix}
7661 This option specifies where to find the executables, libraries,
7662 include files, and data files of the compiler itself.
7664 The compiler driver program runs one or more of the subprograms
7665 @file{cpp}, @file{cc1}, @file{as} and @file{ld}. It tries
7666 @var{prefix} as a prefix for each program it tries to run, both with and
7667 without @samp{@var{machine}/@var{version}/} (@pxref{Target Options}).
7669 For each subprogram to be run, the compiler driver first tries the
7670 @option{-B} prefix, if any. If that name is not found, or if @option{-B}
7671 was not specified, the driver tries two standard prefixes, which are
7672 @file{/usr/lib/gcc/} and @file{/usr/local/lib/gcc/}. If neither of
7673 those results in a file name that is found, the unmodified program
7674 name is searched for using the directories specified in your
7675 @env{PATH} environment variable.
7677 The compiler will check to see if the path provided by the @option{-B}
7678 refers to a directory, and if necessary it will add a directory
7679 separator character at the end of the path.
7681 @option{-B} prefixes that effectively specify directory names also apply
7682 to libraries in the linker, because the compiler translates these
7683 options into @option{-L} options for the linker. They also apply to
7684 includes files in the preprocessor, because the compiler translates these
7685 options into @option{-isystem} options for the preprocessor. In this case,
7686 the compiler appends @samp{include} to the prefix.
7688 The run-time support file @file{libgcc.a} can also be searched for using
7689 the @option{-B} prefix, if needed. If it is not found there, the two
7690 standard prefixes above are tried, and that is all. The file is left
7691 out of the link if it is not found by those means.
7693 Another way to specify a prefix much like the @option{-B} prefix is to use
7694 the environment variable @env{GCC_EXEC_PREFIX}. @xref{Environment
7697 As a special kludge, if the path provided by @option{-B} is
7698 @file{[dir/]stage@var{N}/}, where @var{N} is a number in the range 0 to
7699 9, then it will be replaced by @file{[dir/]include}. This is to help
7700 with boot-strapping the compiler.
7702 @item -specs=@var{file}
7704 Process @var{file} after the compiler reads in the standard @file{specs}
7705 file, in order to override the defaults that the @file{gcc} driver
7706 program uses when determining what switches to pass to @file{cc1},
7707 @file{cc1plus}, @file{as}, @file{ld}, etc. More than one
7708 @option{-specs=@var{file}} can be specified on the command line, and they
7709 are processed in order, from left to right.
7711 @item --sysroot=@var{dir}
7713 Use @var{dir} as the logical root directory for headers and libraries.
7714 For example, if the compiler would normally search for headers in
7715 @file{/usr/include} and libraries in @file{/usr/lib}, it will instead
7716 search @file{@var{dir}/usr/include} and @file{@var{dir}/usr/lib}.
7718 If you use both this option and the @option{-isysroot} option, then
7719 the @option{--sysroot} option will apply to libraries, but the
7720 @option{-isysroot} option will apply to header files.
7722 The GNU linker (beginning with version 2.16) has the necessary support
7723 for this option. If your linker does not support this option, the
7724 header file aspect of @option{--sysroot} will still work, but the
7725 library aspect will not.
7729 This option has been deprecated. Please use @option{-iquote} instead for
7730 @option{-I} directories before the @option{-I-} and remove the @option{-I-}.
7731 Any directories you specify with @option{-I} options before the @option{-I-}
7732 option are searched only for the case of @samp{#include "@var{file}"};
7733 they are not searched for @samp{#include <@var{file}>}.
7735 If additional directories are specified with @option{-I} options after
7736 the @option{-I-}, these directories are searched for all @samp{#include}
7737 directives. (Ordinarily @emph{all} @option{-I} directories are used
7740 In addition, the @option{-I-} option inhibits the use of the current
7741 directory (where the current input file came from) as the first search
7742 directory for @samp{#include "@var{file}"}. There is no way to
7743 override this effect of @option{-I-}. With @option{-I.} you can specify
7744 searching the directory which was current when the compiler was
7745 invoked. That is not exactly the same as what the preprocessor does
7746 by default, but it is often satisfactory.
7748 @option{-I-} does not inhibit the use of the standard system directories
7749 for header files. Thus, @option{-I-} and @option{-nostdinc} are
7756 @section Specifying subprocesses and the switches to pass to them
7759 @command{gcc} is a driver program. It performs its job by invoking a
7760 sequence of other programs to do the work of compiling, assembling and
7761 linking. GCC interprets its command-line parameters and uses these to
7762 deduce which programs it should invoke, and which command-line options
7763 it ought to place on their command lines. This behavior is controlled
7764 by @dfn{spec strings}. In most cases there is one spec string for each
7765 program that GCC can invoke, but a few programs have multiple spec
7766 strings to control their behavior. The spec strings built into GCC can
7767 be overridden by using the @option{-specs=} command-line switch to specify
7770 @dfn{Spec files} are plaintext files that are used to construct spec
7771 strings. They consist of a sequence of directives separated by blank
7772 lines. The type of directive is determined by the first non-whitespace
7773 character on the line and it can be one of the following:
7776 @item %@var{command}
7777 Issues a @var{command} to the spec file processor. The commands that can
7781 @item %include <@var{file}>
7783 Search for @var{file} and insert its text at the current point in the
7786 @item %include_noerr <@var{file}>
7787 @cindex %include_noerr
7788 Just like @samp{%include}, but do not generate an error message if the include
7789 file cannot be found.
7791 @item %rename @var{old_name} @var{new_name}
7793 Rename the spec string @var{old_name} to @var{new_name}.
7797 @item *[@var{spec_name}]:
7798 This tells the compiler to create, override or delete the named spec
7799 string. All lines after this directive up to the next directive or
7800 blank line are considered to be the text for the spec string. If this
7801 results in an empty string then the spec will be deleted. (Or, if the
7802 spec did not exist, then nothing will happened.) Otherwise, if the spec
7803 does not currently exist a new spec will be created. If the spec does
7804 exist then its contents will be overridden by the text of this
7805 directive, unless the first character of that text is the @samp{+}
7806 character, in which case the text will be appended to the spec.
7808 @item [@var{suffix}]:
7809 Creates a new @samp{[@var{suffix}] spec} pair. All lines after this directive
7810 and up to the next directive or blank line are considered to make up the
7811 spec string for the indicated suffix. When the compiler encounters an
7812 input file with the named suffix, it will processes the spec string in
7813 order to work out how to compile that file. For example:
7820 This says that any input file whose name ends in @samp{.ZZ} should be
7821 passed to the program @samp{z-compile}, which should be invoked with the
7822 command-line switch @option{-input} and with the result of performing the
7823 @samp{%i} substitution. (See below.)
7825 As an alternative to providing a spec string, the text that follows a
7826 suffix directive can be one of the following:
7829 @item @@@var{language}
7830 This says that the suffix is an alias for a known @var{language}. This is
7831 similar to using the @option{-x} command-line switch to GCC to specify a
7832 language explicitly. For example:
7839 Says that .ZZ files are, in fact, C++ source files.
7842 This causes an error messages saying:
7845 @var{name} compiler not installed on this system.
7849 GCC already has an extensive list of suffixes built into it.
7850 This directive will add an entry to the end of the list of suffixes, but
7851 since the list is searched from the end backwards, it is effectively
7852 possible to override earlier entries using this technique.
7856 GCC has the following spec strings built into it. Spec files can
7857 override these strings or create their own. Note that individual
7858 targets can also add their own spec strings to this list.
7861 asm Options to pass to the assembler
7862 asm_final Options to pass to the assembler post-processor
7863 cpp Options to pass to the C preprocessor
7864 cc1 Options to pass to the C compiler
7865 cc1plus Options to pass to the C++ compiler
7866 endfile Object files to include at the end of the link
7867 link Options to pass to the linker
7868 lib Libraries to include on the command line to the linker
7869 libgcc Decides which GCC support library to pass to the linker
7870 linker Sets the name of the linker
7871 predefines Defines to be passed to the C preprocessor
7872 signed_char Defines to pass to CPP to say whether @code{char} is signed
7874 startfile Object files to include at the start of the link
7877 Here is a small example of a spec file:
7883 --start-group -lgcc -lc -leval1 --end-group %(old_lib)
7886 This example renames the spec called @samp{lib} to @samp{old_lib} and
7887 then overrides the previous definition of @samp{lib} with a new one.
7888 The new definition adds in some extra command-line options before
7889 including the text of the old definition.
7891 @dfn{Spec strings} are a list of command-line options to be passed to their
7892 corresponding program. In addition, the spec strings can contain
7893 @samp{%}-prefixed sequences to substitute variable text or to
7894 conditionally insert text into the command line. Using these constructs
7895 it is possible to generate quite complex command lines.
7897 Here is a table of all defined @samp{%}-sequences for spec
7898 strings. Note that spaces are not generated automatically around the
7899 results of expanding these sequences. Therefore you can concatenate them
7900 together or combine them with constant text in a single argument.
7904 Substitute one @samp{%} into the program name or argument.
7907 Substitute the name of the input file being processed.
7910 Substitute the basename of the input file being processed.
7911 This is the substring up to (and not including) the last period
7912 and not including the directory.
7915 This is the same as @samp{%b}, but include the file suffix (text after
7919 Marks the argument containing or following the @samp{%d} as a
7920 temporary file name, so that that file will be deleted if GCC exits
7921 successfully. Unlike @samp{%g}, this contributes no text to the
7924 @item %g@var{suffix}
7925 Substitute a file name that has suffix @var{suffix} and is chosen
7926 once per compilation, and mark the argument in the same way as
7927 @samp{%d}. To reduce exposure to denial-of-service attacks, the file
7928 name is now chosen in a way that is hard to predict even when previously
7929 chosen file names are known. For example, @samp{%g.s @dots{} %g.o @dots{} %g.s}
7930 might turn into @samp{ccUVUUAU.s ccXYAXZ12.o ccUVUUAU.s}. @var{suffix} matches
7931 the regexp @samp{[.A-Za-z]*} or the special string @samp{%O}, which is
7932 treated exactly as if @samp{%O} had been preprocessed. Previously, @samp{%g}
7933 was simply substituted with a file name chosen once per compilation,
7934 without regard to any appended suffix (which was therefore treated
7935 just like ordinary text), making such attacks more likely to succeed.
7937 @item %u@var{suffix}
7938 Like @samp{%g}, but generates a new temporary file name even if
7939 @samp{%u@var{suffix}} was already seen.
7941 @item %U@var{suffix}
7942 Substitutes the last file name generated with @samp{%u@var{suffix}}, generating a
7943 new one if there is no such last file name. In the absence of any
7944 @samp{%u@var{suffix}}, this is just like @samp{%g@var{suffix}}, except they don't share
7945 the same suffix @emph{space}, so @samp{%g.s @dots{} %U.s @dots{} %g.s @dots{} %U.s}
7946 would involve the generation of two distinct file names, one
7947 for each @samp{%g.s} and another for each @samp{%U.s}. Previously, @samp{%U} was
7948 simply substituted with a file name chosen for the previous @samp{%u},
7949 without regard to any appended suffix.
7951 @item %j@var{suffix}
7952 Substitutes the name of the @code{HOST_BIT_BUCKET}, if any, and if it is
7953 writable, and if save-temps is off; otherwise, substitute the name
7954 of a temporary file, just like @samp{%u}. This temporary file is not
7955 meant for communication between processes, but rather as a junk
7958 @item %|@var{suffix}
7959 @itemx %m@var{suffix}
7960 Like @samp{%g}, except if @option{-pipe} is in effect. In that case
7961 @samp{%|} substitutes a single dash and @samp{%m} substitutes nothing at
7962 all. These are the two most common ways to instruct a program that it
7963 should read from standard input or write to standard output. If you
7964 need something more elaborate you can use an @samp{%@{pipe:@code{X}@}}
7965 construct: see for example @file{f/lang-specs.h}.
7967 @item %.@var{SUFFIX}
7968 Substitutes @var{.SUFFIX} for the suffixes of a matched switch's args
7969 when it is subsequently output with @samp{%*}. @var{SUFFIX} is
7970 terminated by the next space or %.
7973 Marks the argument containing or following the @samp{%w} as the
7974 designated output file of this compilation. This puts the argument
7975 into the sequence of arguments that @samp{%o} will substitute later.
7978 Substitutes the names of all the output files, with spaces
7979 automatically placed around them. You should write spaces
7980 around the @samp{%o} as well or the results are undefined.
7981 @samp{%o} is for use in the specs for running the linker.
7982 Input files whose names have no recognized suffix are not compiled
7983 at all, but they are included among the output files, so they will
7987 Substitutes the suffix for object files. Note that this is
7988 handled specially when it immediately follows @samp{%g, %u, or %U},
7989 because of the need for those to form complete file names. The
7990 handling is such that @samp{%O} is treated exactly as if it had already
7991 been substituted, except that @samp{%g, %u, and %U} do not currently
7992 support additional @var{suffix} characters following @samp{%O} as they would
7993 following, for example, @samp{.o}.
7996 Substitutes the standard macro predefinitions for the
7997 current target machine. Use this when running @code{cpp}.
8000 Like @samp{%p}, but puts @samp{__} before and after the name of each
8001 predefined macro, except for macros that start with @samp{__} or with
8002 @samp{_@var{L}}, where @var{L} is an uppercase letter. This is for ISO
8006 Substitute any of @option{-iprefix} (made from @env{GCC_EXEC_PREFIX}),
8007 @option{-isysroot} (made from @env{TARGET_SYSTEM_ROOT}),
8008 @option{-isystem} (made from @env{COMPILER_PATH} and @option{-B} options)
8009 and @option{-imultilib} as necessary.
8012 Current argument is the name of a library or startup file of some sort.
8013 Search for that file in a standard list of directories and substitute
8014 the full name found.
8017 Print @var{str} as an error message. @var{str} is terminated by a newline.
8018 Use this when inconsistent options are detected.
8021 Substitute the contents of spec string @var{name} at this point.
8024 Like @samp{%(@dots{})} but put @samp{__} around @option{-D} arguments.
8026 @item %x@{@var{option}@}
8027 Accumulate an option for @samp{%X}.
8030 Output the accumulated linker options specified by @option{-Wl} or a @samp{%x}
8034 Output the accumulated assembler options specified by @option{-Wa}.
8037 Output the accumulated preprocessor options specified by @option{-Wp}.
8040 Process the @code{asm} spec. This is used to compute the
8041 switches to be passed to the assembler.
8044 Process the @code{asm_final} spec. This is a spec string for
8045 passing switches to an assembler post-processor, if such a program is
8049 Process the @code{link} spec. This is the spec for computing the
8050 command line passed to the linker. Typically it will make use of the
8051 @samp{%L %G %S %D and %E} sequences.
8054 Dump out a @option{-L} option for each directory that GCC believes might
8055 contain startup files. If the target supports multilibs then the
8056 current multilib directory will be prepended to each of these paths.
8059 Process the @code{lib} spec. This is a spec string for deciding which
8060 libraries should be included on the command line to the linker.
8063 Process the @code{libgcc} spec. This is a spec string for deciding
8064 which GCC support library should be included on the command line to the linker.
8067 Process the @code{startfile} spec. This is a spec for deciding which
8068 object files should be the first ones passed to the linker. Typically
8069 this might be a file named @file{crt0.o}.
8072 Process the @code{endfile} spec. This is a spec string that specifies
8073 the last object files that will be passed to the linker.
8076 Process the @code{cpp} spec. This is used to construct the arguments
8077 to be passed to the C preprocessor.
8080 Process the @code{cc1} spec. This is used to construct the options to be
8081 passed to the actual C compiler (@samp{cc1}).
8084 Process the @code{cc1plus} spec. This is used to construct the options to be
8085 passed to the actual C++ compiler (@samp{cc1plus}).
8088 Substitute the variable part of a matched option. See below.
8089 Note that each comma in the substituted string is replaced by
8093 Remove all occurrences of @code{-S} from the command line. Note---this
8094 command is position dependent. @samp{%} commands in the spec string
8095 before this one will see @code{-S}, @samp{%} commands in the spec string
8096 after this one will not.
8098 @item %:@var{function}(@var{args})
8099 Call the named function @var{function}, passing it @var{args}.
8100 @var{args} is first processed as a nested spec string, then split
8101 into an argument vector in the usual fashion. The function returns
8102 a string which is processed as if it had appeared literally as part
8103 of the current spec.
8105 The following built-in spec functions are provided:
8109 The @code{getenv} spec function takes two arguments: an environment
8110 variable name and a string. If the environment variable is not
8111 defined, a fatal error is issued. Otherwise, the return value is the
8112 value of the environment variable concatenated with the string. For
8113 example, if @env{TOPDIR} is defined as @file{/path/to/top}, then:
8116 %:getenv(TOPDIR /include)
8119 expands to @file{/path/to/top/include}.
8121 @item @code{if-exists}
8122 The @code{if-exists} spec function takes one argument, an absolute
8123 pathname to a file. If the file exists, @code{if-exists} returns the
8124 pathname. Here is a small example of its usage:
8128 crt0%O%s %:if-exists(crti%O%s) crtbegin%O%s
8131 @item @code{if-exists-else}
8132 The @code{if-exists-else} spec function is similar to the @code{if-exists}
8133 spec function, except that it takes two arguments. The first argument is
8134 an absolute pathname to a file. If the file exists, @code{if-exists-else}
8135 returns the pathname. If it does not exist, it returns the second argument.
8136 This way, @code{if-exists-else} can be used to select one file or another,
8137 based on the existence of the first. Here is a small example of its usage:
8141 crt0%O%s %:if-exists(crti%O%s) \
8142 %:if-exists-else(crtbeginT%O%s crtbegin%O%s)
8145 @item @code{replace-outfile}
8146 The @code{replace-outfile} spec function takes two arguments. It looks for the
8147 first argument in the outfiles array and replaces it with the second argument. Here
8148 is a small example of its usage:
8151 %@{fgnu-runtime:%:replace-outfile(-lobjc -lobjc-gnu)@}
8154 @item @code{print-asm-header}
8155 The @code{print-asm-header} function takes no arguments and simply
8156 prints a banner like:
8162 Use "-Wa,OPTION" to pass "OPTION" to the assembler.
8165 It is used to separate compiler options from assembler options
8166 in the @option{--target-help} output.
8170 Substitutes the @code{-S} switch, if that switch was given to GCC@.
8171 If that switch was not specified, this substitutes nothing. Note that
8172 the leading dash is omitted when specifying this option, and it is
8173 automatically inserted if the substitution is performed. Thus the spec
8174 string @samp{%@{foo@}} would match the command-line option @option{-foo}
8175 and would output the command line option @option{-foo}.
8177 @item %W@{@code{S}@}
8178 Like %@{@code{S}@} but mark last argument supplied within as a file to be
8181 @item %@{@code{S}*@}
8182 Substitutes all the switches specified to GCC whose names start
8183 with @code{-S}, but which also take an argument. This is used for
8184 switches like @option{-o}, @option{-D}, @option{-I}, etc.
8185 GCC considers @option{-o foo} as being
8186 one switch whose names starts with @samp{o}. %@{o*@} would substitute this
8187 text, including the space. Thus two arguments would be generated.
8189 @item %@{@code{S}*&@code{T}*@}
8190 Like %@{@code{S}*@}, but preserve order of @code{S} and @code{T} options
8191 (the order of @code{S} and @code{T} in the spec is not significant).
8192 There can be any number of ampersand-separated variables; for each the
8193 wild card is optional. Useful for CPP as @samp{%@{D*&U*&A*@}}.
8195 @item %@{@code{S}:@code{X}@}
8196 Substitutes @code{X}, if the @samp{-S} switch was given to GCC@.
8198 @item %@{!@code{S}:@code{X}@}
8199 Substitutes @code{X}, if the @samp{-S} switch was @emph{not} given to GCC@.
8201 @item %@{@code{S}*:@code{X}@}
8202 Substitutes @code{X} if one or more switches whose names start with
8203 @code{-S} are specified to GCC@. Normally @code{X} is substituted only
8204 once, no matter how many such switches appeared. However, if @code{%*}
8205 appears somewhere in @code{X}, then @code{X} will be substituted once
8206 for each matching switch, with the @code{%*} replaced by the part of
8207 that switch that matched the @code{*}.
8209 @item %@{.@code{S}:@code{X}@}
8210 Substitutes @code{X}, if processing a file with suffix @code{S}.
8212 @item %@{!.@code{S}:@code{X}@}
8213 Substitutes @code{X}, if @emph{not} processing a file with suffix @code{S}.
8215 @item %@{,@code{S}:@code{X}@}
8216 Substitutes @code{X}, if processing a file for language @code{S}.
8218 @item %@{!,@code{S}:@code{X}@}
8219 Substitutes @code{X}, if not processing a file for language @code{S}.
8221 @item %@{@code{S}|@code{P}:@code{X}@}
8222 Substitutes @code{X} if either @code{-S} or @code{-P} was given to
8223 GCC@. This may be combined with @samp{!}, @samp{.}, @samp{,}, and
8224 @code{*} sequences as well, although they have a stronger binding than
8225 the @samp{|}. If @code{%*} appears in @code{X}, all of the
8226 alternatives must be starred, and only the first matching alternative
8229 For example, a spec string like this:
8232 %@{.c:-foo@} %@{!.c:-bar@} %@{.c|d:-baz@} %@{!.c|d:-boggle@}
8235 will output the following command-line options from the following input
8236 command-line options:
8241 -d fred.c -foo -baz -boggle
8242 -d jim.d -bar -baz -boggle
8245 @item %@{S:X; T:Y; :D@}
8247 If @code{S} was given to GCC, substitutes @code{X}; else if @code{T} was
8248 given to GCC, substitutes @code{Y}; else substitutes @code{D}. There can
8249 be as many clauses as you need. This may be combined with @code{.},
8250 @code{,}, @code{!}, @code{|}, and @code{*} as needed.
8255 The conditional text @code{X} in a %@{@code{S}:@code{X}@} or similar
8256 construct may contain other nested @samp{%} constructs or spaces, or
8257 even newlines. They are processed as usual, as described above.
8258 Trailing white space in @code{X} is ignored. White space may also
8259 appear anywhere on the left side of the colon in these constructs,
8260 except between @code{.} or @code{*} and the corresponding word.
8262 The @option{-O}, @option{-f}, @option{-m}, and @option{-W} switches are
8263 handled specifically in these constructs. If another value of
8264 @option{-O} or the negated form of a @option{-f}, @option{-m}, or
8265 @option{-W} switch is found later in the command line, the earlier
8266 switch value is ignored, except with @{@code{S}*@} where @code{S} is
8267 just one letter, which passes all matching options.
8269 The character @samp{|} at the beginning of the predicate text is used to
8270 indicate that a command should be piped to the following command, but
8271 only if @option{-pipe} is specified.
8273 It is built into GCC which switches take arguments and which do not.
8274 (You might think it would be useful to generalize this to allow each
8275 compiler's spec to say which switches take arguments. But this cannot
8276 be done in a consistent fashion. GCC cannot even decide which input
8277 files have been specified without knowing which switches take arguments,
8278 and it must know which input files to compile in order to tell which
8281 GCC also knows implicitly that arguments starting in @option{-l} are to be
8282 treated as compiler output files, and passed to the linker in their
8283 proper position among the other output files.
8285 @c man begin OPTIONS
8287 @node Target Options
8288 @section Specifying Target Machine and Compiler Version
8289 @cindex target options
8290 @cindex cross compiling
8291 @cindex specifying machine version
8292 @cindex specifying compiler version and target machine
8293 @cindex compiler version, specifying
8294 @cindex target machine, specifying
8296 The usual way to run GCC is to run the executable called @file{gcc}, or
8297 @file{<machine>-gcc} when cross-compiling, or
8298 @file{<machine>-gcc-<version>} to run a version other than the one that
8299 was installed last. Sometimes this is inconvenient, so GCC provides
8300 options that will switch to another cross-compiler or version.
8303 @item -b @var{machine}
8305 The argument @var{machine} specifies the target machine for compilation.
8307 The value to use for @var{machine} is the same as was specified as the
8308 machine type when configuring GCC as a cross-compiler. For
8309 example, if a cross-compiler was configured with @samp{configure
8310 arm-elf}, meaning to compile for an arm processor with elf binaries,
8311 then you would specify @option{-b arm-elf} to run that cross compiler.
8312 Because there are other options beginning with @option{-b}, the
8313 configuration must contain a hyphen.
8315 @item -V @var{version}
8317 The argument @var{version} specifies which version of GCC to run.
8318 This is useful when multiple versions are installed. For example,
8319 @var{version} might be @samp{4.0}, meaning to run GCC version 4.0.
8322 The @option{-V} and @option{-b} options work by running the
8323 @file{<machine>-gcc-<version>} executable, so there's no real reason to
8324 use them if you can just run that directly.
8326 @node Submodel Options
8327 @section Hardware Models and Configurations
8328 @cindex submodel options
8329 @cindex specifying hardware config
8330 @cindex hardware models and configurations, specifying
8331 @cindex machine dependent options
8333 Earlier we discussed the standard option @option{-b} which chooses among
8334 different installed compilers for completely different target
8335 machines, such as VAX vs.@: 68000 vs.@: 80386.
8337 In addition, each of these target machine types can have its own
8338 special options, starting with @samp{-m}, to choose among various
8339 hardware models or configurations---for example, 68010 vs 68020,
8340 floating coprocessor or none. A single installed version of the
8341 compiler can compile for any model or configuration, according to the
8344 Some configurations of the compiler also support additional special
8345 options, usually for compatibility with other compilers on the same
8348 @c This list is ordered alphanumerically by subsection name.
8349 @c It should be the same order and spelling as these options are listed
8350 @c in Machine Dependent Options
8356 * Blackfin Options::
8360 * DEC Alpha Options::
8361 * DEC Alpha/VMS Options::
8363 * GNU/Linux Options::
8366 * i386 and x86-64 Options::
8379 * RS/6000 and PowerPC Options::
8380 * S/390 and zSeries Options::
8385 * System V Options::
8390 * Xstormy16 Options::
8396 @subsection ARC Options
8399 These options are defined for ARC implementations:
8404 Compile code for little endian mode. This is the default.
8408 Compile code for big endian mode.
8411 @opindex mmangle-cpu
8412 Prepend the name of the cpu to all public symbol names.
8413 In multiple-processor systems, there are many ARC variants with different
8414 instruction and register set characteristics. This flag prevents code
8415 compiled for one cpu to be linked with code compiled for another.
8416 No facility exists for handling variants that are ``almost identical''.
8417 This is an all or nothing option.
8419 @item -mcpu=@var{cpu}
8421 Compile code for ARC variant @var{cpu}.
8422 Which variants are supported depend on the configuration.
8423 All variants support @option{-mcpu=base}, this is the default.
8425 @item -mtext=@var{text-section}
8426 @itemx -mdata=@var{data-section}
8427 @itemx -mrodata=@var{readonly-data-section}
8431 Put functions, data, and readonly data in @var{text-section},
8432 @var{data-section}, and @var{readonly-data-section} respectively
8433 by default. This can be overridden with the @code{section} attribute.
8434 @xref{Variable Attributes}.
8439 @subsection ARM Options
8442 These @samp{-m} options are defined for Advanced RISC Machines (ARM)
8446 @item -mabi=@var{name}
8448 Generate code for the specified ABI@. Permissible values are: @samp{apcs-gnu},
8449 @samp{atpcs}, @samp{aapcs}, @samp{aapcs-linux} and @samp{iwmmxt}.
8452 @opindex mapcs-frame
8453 Generate a stack frame that is compliant with the ARM Procedure Call
8454 Standard for all functions, even if this is not strictly necessary for
8455 correct execution of the code. Specifying @option{-fomit-frame-pointer}
8456 with this option will cause the stack frames not to be generated for
8457 leaf functions. The default is @option{-mno-apcs-frame}.
8461 This is a synonym for @option{-mapcs-frame}.
8464 @c not currently implemented
8465 @item -mapcs-stack-check
8466 @opindex mapcs-stack-check
8467 Generate code to check the amount of stack space available upon entry to
8468 every function (that actually uses some stack space). If there is
8469 insufficient space available then either the function
8470 @samp{__rt_stkovf_split_small} or @samp{__rt_stkovf_split_big} will be
8471 called, depending upon the amount of stack space required. The run time
8472 system is required to provide these functions. The default is
8473 @option{-mno-apcs-stack-check}, since this produces smaller code.
8475 @c not currently implemented
8477 @opindex mapcs-float
8478 Pass floating point arguments using the float point registers. This is
8479 one of the variants of the APCS@. This option is recommended if the
8480 target hardware has a floating point unit or if a lot of floating point
8481 arithmetic is going to be performed by the code. The default is
8482 @option{-mno-apcs-float}, since integer only code is slightly increased in
8483 size if @option{-mapcs-float} is used.
8485 @c not currently implemented
8486 @item -mapcs-reentrant
8487 @opindex mapcs-reentrant
8488 Generate reentrant, position independent code. The default is
8489 @option{-mno-apcs-reentrant}.
8492 @item -mthumb-interwork
8493 @opindex mthumb-interwork
8494 Generate code which supports calling between the ARM and Thumb
8495 instruction sets. Without this option the two instruction sets cannot
8496 be reliably used inside one program. The default is
8497 @option{-mno-thumb-interwork}, since slightly larger code is generated
8498 when @option{-mthumb-interwork} is specified.
8500 @item -mno-sched-prolog
8501 @opindex mno-sched-prolog
8502 Prevent the reordering of instructions in the function prolog, or the
8503 merging of those instruction with the instructions in the function's
8504 body. This means that all functions will start with a recognizable set
8505 of instructions (or in fact one of a choice from a small set of
8506 different function prologues), and this information can be used to
8507 locate the start if functions inside an executable piece of code. The
8508 default is @option{-msched-prolog}.
8511 @opindex mhard-float
8512 Generate output containing floating point instructions. This is the
8516 @opindex msoft-float
8517 Generate output containing library calls for floating point.
8518 @strong{Warning:} the requisite libraries are not available for all ARM
8519 targets. Normally the facilities of the machine's usual C compiler are
8520 used, but this cannot be done directly in cross-compilation. You must make
8521 your own arrangements to provide suitable library functions for
8524 @option{-msoft-float} changes the calling convention in the output file;
8525 therefore, it is only useful if you compile @emph{all} of a program with
8526 this option. In particular, you need to compile @file{libgcc.a}, the
8527 library that comes with GCC, with @option{-msoft-float} in order for
8530 @item -mfloat-abi=@var{name}
8532 Specifies which ABI to use for floating point values. Permissible values
8533 are: @samp{soft}, @samp{softfp} and @samp{hard}.
8535 @samp{soft} and @samp{hard} are equivalent to @option{-msoft-float}
8536 and @option{-mhard-float} respectively. @samp{softfp} allows the generation
8537 of floating point instructions, but still uses the soft-float calling
8540 @item -mlittle-endian
8541 @opindex mlittle-endian
8542 Generate code for a processor running in little-endian mode. This is
8543 the default for all standard configurations.
8546 @opindex mbig-endian
8547 Generate code for a processor running in big-endian mode; the default is
8548 to compile code for a little-endian processor.
8550 @item -mwords-little-endian
8551 @opindex mwords-little-endian
8552 This option only applies when generating code for big-endian processors.
8553 Generate code for a little-endian word order but a big-endian byte
8554 order. That is, a byte order of the form @samp{32107654}. Note: this
8555 option should only be used if you require compatibility with code for
8556 big-endian ARM processors generated by versions of the compiler prior to
8559 @item -mcpu=@var{name}
8561 This specifies the name of the target ARM processor. GCC uses this name
8562 to determine what kind of instructions it can emit when generating
8563 assembly code. Permissible names are: @samp{arm2}, @samp{arm250},
8564 @samp{arm3}, @samp{arm6}, @samp{arm60}, @samp{arm600}, @samp{arm610},
8565 @samp{arm620}, @samp{arm7}, @samp{arm7m}, @samp{arm7d}, @samp{arm7dm},
8566 @samp{arm7di}, @samp{arm7dmi}, @samp{arm70}, @samp{arm700},
8567 @samp{arm700i}, @samp{arm710}, @samp{arm710c}, @samp{arm7100},
8568 @samp{arm7500}, @samp{arm7500fe}, @samp{arm7tdmi}, @samp{arm7tdmi-s},
8569 @samp{arm8}, @samp{strongarm}, @samp{strongarm110}, @samp{strongarm1100},
8570 @samp{arm8}, @samp{arm810}, @samp{arm9}, @samp{arm9e}, @samp{arm920},
8571 @samp{arm920t}, @samp{arm922t}, @samp{arm946e-s}, @samp{arm966e-s},
8572 @samp{arm968e-s}, @samp{arm926ej-s}, @samp{arm940t}, @samp{arm9tdmi},
8573 @samp{arm10tdmi}, @samp{arm1020t}, @samp{arm1026ej-s},
8574 @samp{arm10e}, @samp{arm1020e}, @samp{arm1022e},
8575 @samp{arm1136j-s}, @samp{arm1136jf-s}, @samp{mpcore}, @samp{mpcorenovfp},
8576 @samp{arm1156t2-s}, @samp{arm1176jz-s}, @samp{arm1176jzf-s},
8577 @samp{cortex-a8}, @samp{cortex-r4}, @samp{cortex-m3}, @samp{cortex-m1},
8578 @samp{xscale}, @samp{iwmmxt}, @samp{ep9312}.
8580 @itemx -mtune=@var{name}
8582 This option is very similar to the @option{-mcpu=} option, except that
8583 instead of specifying the actual target processor type, and hence
8584 restricting which instructions can be used, it specifies that GCC should
8585 tune the performance of the code as if the target were of the type
8586 specified in this option, but still choosing the instructions that it
8587 will generate based on the cpu specified by a @option{-mcpu=} option.
8588 For some ARM implementations better performance can be obtained by using
8591 @item -march=@var{name}
8593 This specifies the name of the target ARM architecture. GCC uses this
8594 name to determine what kind of instructions it can emit when generating
8595 assembly code. This option can be used in conjunction with or instead
8596 of the @option{-mcpu=} option. Permissible names are: @samp{armv2},
8597 @samp{armv2a}, @samp{armv3}, @samp{armv3m}, @samp{armv4}, @samp{armv4t},
8598 @samp{armv5}, @samp{armv5t}, @samp{armv5te}, @samp{armv6}, @samp{armv6j},
8599 @samp{armv6t2}, @samp{armv6z}, @samp{armv6zk}, @samp{armv6-m},
8600 @samp{armv7}, @samp{armv7-a}, @samp{armv7-r}, @samp{armv7-m},
8601 @samp{iwmmxt}, @samp{ep9312}.
8603 @item -mfpu=@var{name}
8604 @itemx -mfpe=@var{number}
8605 @itemx -mfp=@var{number}
8609 This specifies what floating point hardware (or hardware emulation) is
8610 available on the target. Permissible names are: @samp{fpa}, @samp{fpe2},
8611 @samp{fpe3}, @samp{maverick}, @samp{vfp}. @option{-mfp} and @option{-mfpe}
8612 are synonyms for @option{-mfpu}=@samp{fpe}@var{number}, for compatibility
8613 with older versions of GCC@.
8615 If @option{-msoft-float} is specified this specifies the format of
8616 floating point values.
8618 @item -mstructure-size-boundary=@var{n}
8619 @opindex mstructure-size-boundary
8620 The size of all structures and unions will be rounded up to a multiple
8621 of the number of bits set by this option. Permissible values are 8, 32
8622 and 64. The default value varies for different toolchains. For the COFF
8623 targeted toolchain the default value is 8. A value of 64 is only allowed
8624 if the underlying ABI supports it.
8626 Specifying the larger number can produce faster, more efficient code, but
8627 can also increase the size of the program. Different values are potentially
8628 incompatible. Code compiled with one value cannot necessarily expect to
8629 work with code or libraries compiled with another value, if they exchange
8630 information using structures or unions.
8632 @item -mabort-on-noreturn
8633 @opindex mabort-on-noreturn
8634 Generate a call to the function @code{abort} at the end of a
8635 @code{noreturn} function. It will be executed if the function tries to
8639 @itemx -mno-long-calls
8640 @opindex mlong-calls
8641 @opindex mno-long-calls
8642 Tells the compiler to perform function calls by first loading the
8643 address of the function into a register and then performing a subroutine
8644 call on this register. This switch is needed if the target function
8645 will lie outside of the 64 megabyte addressing range of the offset based
8646 version of subroutine call instruction.
8648 Even if this switch is enabled, not all function calls will be turned
8649 into long calls. The heuristic is that static functions, functions
8650 which have the @samp{short-call} attribute, functions that are inside
8651 the scope of a @samp{#pragma no_long_calls} directive and functions whose
8652 definitions have already been compiled within the current compilation
8653 unit, will not be turned into long calls. The exception to this rule is
8654 that weak function definitions, functions with the @samp{long-call}
8655 attribute or the @samp{section} attribute, and functions that are within
8656 the scope of a @samp{#pragma long_calls} directive, will always be
8657 turned into long calls.
8659 This feature is not enabled by default. Specifying
8660 @option{-mno-long-calls} will restore the default behavior, as will
8661 placing the function calls within the scope of a @samp{#pragma
8662 long_calls_off} directive. Note these switches have no effect on how
8663 the compiler generates code to handle function calls via function
8666 @item -mnop-fun-dllimport
8667 @opindex mnop-fun-dllimport
8668 Disable support for the @code{dllimport} attribute.
8670 @item -msingle-pic-base
8671 @opindex msingle-pic-base
8672 Treat the register used for PIC addressing as read-only, rather than
8673 loading it in the prologue for each function. The run-time system is
8674 responsible for initializing this register with an appropriate value
8675 before execution begins.
8677 @item -mpic-register=@var{reg}
8678 @opindex mpic-register
8679 Specify the register to be used for PIC addressing. The default is R10
8680 unless stack-checking is enabled, when R9 is used.
8682 @item -mcirrus-fix-invalid-insns
8683 @opindex mcirrus-fix-invalid-insns
8684 @opindex mno-cirrus-fix-invalid-insns
8685 Insert NOPs into the instruction stream to in order to work around
8686 problems with invalid Maverick instruction combinations. This option
8687 is only valid if the @option{-mcpu=ep9312} option has been used to
8688 enable generation of instructions for the Cirrus Maverick floating
8689 point co-processor. This option is not enabled by default, since the
8690 problem is only present in older Maverick implementations. The default
8691 can be re-enabled by use of the @option{-mno-cirrus-fix-invalid-insns}
8694 @item -mpoke-function-name
8695 @opindex mpoke-function-name
8696 Write the name of each function into the text section, directly
8697 preceding the function prologue. The generated code is similar to this:
8701 .ascii "arm_poke_function_name", 0
8704 .word 0xff000000 + (t1 - t0)
8705 arm_poke_function_name
8707 stmfd sp!, @{fp, ip, lr, pc@}
8711 When performing a stack backtrace, code can inspect the value of
8712 @code{pc} stored at @code{fp + 0}. If the trace function then looks at
8713 location @code{pc - 12} and the top 8 bits are set, then we know that
8714 there is a function name embedded immediately preceding this location
8715 and has length @code{((pc[-3]) & 0xff000000)}.
8719 Generate code for the Thumb instruction set. The default is to
8720 use the 32-bit ARM instruction set.
8721 This option automatically enables either 16-bit Thumb-1 or
8722 mixed 16/32-bit Thumb-2 instructions based on the @option{-mcpu=@var{name}}
8723 and @option{-march=@var{name}} options.
8726 @opindex mtpcs-frame
8727 Generate a stack frame that is compliant with the Thumb Procedure Call
8728 Standard for all non-leaf functions. (A leaf function is one that does
8729 not call any other functions.) The default is @option{-mno-tpcs-frame}.
8731 @item -mtpcs-leaf-frame
8732 @opindex mtpcs-leaf-frame
8733 Generate a stack frame that is compliant with the Thumb Procedure Call
8734 Standard for all leaf functions. (A leaf function is one that does
8735 not call any other functions.) The default is @option{-mno-apcs-leaf-frame}.
8737 @item -mcallee-super-interworking
8738 @opindex mcallee-super-interworking
8739 Gives all externally visible functions in the file being compiled an ARM
8740 instruction set header which switches to Thumb mode before executing the
8741 rest of the function. This allows these functions to be called from
8742 non-interworking code.
8744 @item -mcaller-super-interworking
8745 @opindex mcaller-super-interworking
8746 Allows calls via function pointers (including virtual functions) to
8747 execute correctly regardless of whether the target code has been
8748 compiled for interworking or not. There is a small overhead in the cost
8749 of executing a function pointer if this option is enabled.
8751 @item -mtp=@var{name}
8753 Specify the access model for the thread local storage pointer. The valid
8754 models are @option{soft}, which generates calls to @code{__aeabi_read_tp},
8755 @option{cp15}, which fetches the thread pointer from @code{cp15} directly
8756 (supported in the arm6k architecture), and @option{auto}, which uses the
8757 best available method for the selected processor. The default setting is
8763 @subsection AVR Options
8766 These options are defined for AVR implementations:
8769 @item -mmcu=@var{mcu}
8771 Specify ATMEL AVR instruction set or MCU type.
8773 Instruction set avr1 is for the minimal AVR core, not supported by the C
8774 compiler, only for assembler programs (MCU types: at90s1200, attiny10,
8775 attiny11, attiny12, attiny15, attiny28).
8777 Instruction set avr2 (default) is for the classic AVR core with up to
8778 8K program memory space (MCU types: at90s2313, at90s2323, attiny22,
8779 at90s2333, at90s2343, at90s4414, at90s4433, at90s4434, at90s8515,
8780 at90c8534, at90s8535).
8782 Instruction set avr3 is for the classic AVR core with up to 128K program
8783 memory space (MCU types: atmega103, atmega603, at43usb320, at76c711).
8785 Instruction set avr4 is for the enhanced AVR core with up to 8K program
8786 memory space (MCU types: atmega8, atmega83, atmega85).
8788 Instruction set avr5 is for the enhanced AVR core with up to 128K program
8789 memory space (MCU types: atmega16, atmega161, atmega163, atmega32, atmega323,
8790 atmega64, atmega128, at43usb355, at94k).
8794 Output instruction sizes to the asm file.
8796 @item -minit-stack=@var{N}
8797 @opindex minit-stack
8798 Specify the initial stack address, which may be a symbol or numeric value,
8799 @samp{__stack} is the default.
8801 @item -mno-interrupts
8802 @opindex mno-interrupts
8803 Generated code is not compatible with hardware interrupts.
8804 Code size will be smaller.
8806 @item -mcall-prologues
8807 @opindex mcall-prologues
8808 Functions prologues/epilogues expanded as call to appropriate
8809 subroutines. Code size will be smaller.
8811 @item -mno-tablejump
8812 @opindex mno-tablejump
8813 Do not generate tablejump insns which sometimes increase code size.
8816 @opindex mtiny-stack
8817 Change only the low 8 bits of the stack pointer.
8821 Assume int to be 8 bit integer. This affects the sizes of all types: A
8822 char will be 1 byte, an int will be 1 byte, an long will be 2 bytes
8823 and long long will be 4 bytes. Please note that this option does not
8824 comply to the C standards, but it will provide you with smaller code
8828 @node Blackfin Options
8829 @subsection Blackfin Options
8830 @cindex Blackfin Options
8833 @item -mcpu=@var{cpu}@r{[}-@var{sirevision}@r{]}
8835 Specifies the name of the target Blackfin processor. Currently, @var{cpu}
8836 can be one of @samp{bf522}, @samp{bf523}, @samp{bf524},
8837 @samp{bf525}, @samp{bf526}, @samp{bf527},
8838 @samp{bf531}, @samp{bf532}, @samp{bf533}, @samp{bf534},
8839 @samp{bf536}, @samp{bf537}, @samp{bf538}, @samp{bf539},
8840 @samp{bf542}, @samp{bf544}, @samp{bf547}, @samp{bf548}, @samp{bf549},
8842 The optional @var{sirevision} specifies the silicon revision of the target
8843 Blackfin processor. Any workarounds available for the targeted silicon revision
8844 will be enabled. If @var{sirevision} is @samp{none}, no workarounds are enabled.
8845 If @var{sirevision} is @samp{any}, all workarounds for the targeted processor
8846 will be enabled. The @code{__SILICON_REVISION__} macro is defined to two
8847 hexadecimal digits representing the major and minor numbers in the silicon
8848 revision. If @var{sirevision} is @samp{none}, the @code{__SILICON_REVISION__}
8849 is not defined. If @var{sirevision} is @samp{any}, the
8850 @code{__SILICON_REVISION__} is defined to be @code{0xffff}.
8851 If this optional @var{sirevision} is not used, GCC assumes the latest known
8852 silicon revision of the targeted Blackfin processor.
8854 Support for @samp{bf561} is incomplete. For @samp{bf561},
8855 Only the processor macro is defined.
8856 Without this option, @samp{bf532} is used as the processor by default.
8857 The corresponding predefined processor macros for @var{cpu} is to
8858 be defined. And for @samp{bfin-elf} toolchain, this causes the hardware BSP
8859 provided by libgloss to be linked in if @option{-msim} is not given.
8863 Specifies that the program will be run on the simulator. This causes
8864 the simulator BSP provided by libgloss to be linked in. This option
8865 has effect only for @samp{bfin-elf} toolchain.
8866 Certain other options, such as @option{-mid-shared-library} and
8867 @option{-mfdpic}, imply @option{-msim}.
8869 @item -momit-leaf-frame-pointer
8870 @opindex momit-leaf-frame-pointer
8871 Don't keep the frame pointer in a register for leaf functions. This
8872 avoids the instructions to save, set up and restore frame pointers and
8873 makes an extra register available in leaf functions. The option
8874 @option{-fomit-frame-pointer} removes the frame pointer for all functions
8875 which might make debugging harder.
8877 @item -mspecld-anomaly
8878 @opindex mspecld-anomaly
8879 When enabled, the compiler will ensure that the generated code does not
8880 contain speculative loads after jump instructions. If this option is used,
8881 @code{__WORKAROUND_SPECULATIVE_LOADS} is defined.
8883 @item -mno-specld-anomaly
8884 @opindex mno-specld-anomaly
8885 Don't generate extra code to prevent speculative loads from occurring.
8887 @item -mcsync-anomaly
8888 @opindex mcsync-anomaly
8889 When enabled, the compiler will ensure that the generated code does not
8890 contain CSYNC or SSYNC instructions too soon after conditional branches.
8891 If this option is used, @code{__WORKAROUND_SPECULATIVE_SYNCS} is defined.
8893 @item -mno-csync-anomaly
8894 @opindex mno-csync-anomaly
8895 Don't generate extra code to prevent CSYNC or SSYNC instructions from
8896 occurring too soon after a conditional branch.
8900 When enabled, the compiler is free to take advantage of the knowledge that
8901 the entire program fits into the low 64k of memory.
8904 @opindex mno-low-64k
8905 Assume that the program is arbitrarily large. This is the default.
8907 @item -mstack-check-l1
8908 @opindex mstack-check-l1
8909 Do stack checking using information placed into L1 scratchpad memory by the
8912 @item -mid-shared-library
8913 @opindex mid-shared-library
8914 Generate code that supports shared libraries via the library ID method.
8915 This allows for execute in place and shared libraries in an environment
8916 without virtual memory management. This option implies @option{-fPIC}.
8917 With a @samp{bfin-elf} target, this option implies @option{-msim}.
8919 @item -mno-id-shared-library
8920 @opindex mno-id-shared-library
8921 Generate code that doesn't assume ID based shared libraries are being used.
8922 This is the default.
8924 @item -mleaf-id-shared-library
8925 @opindex mleaf-id-shared-library
8926 Generate code that supports shared libraries via the library ID method,
8927 but assumes that this library or executable won't link against any other
8928 ID shared libraries. That allows the compiler to use faster code for jumps
8931 @item -mno-leaf-id-shared-library
8932 @opindex mno-leaf-id-shared-library
8933 Do not assume that the code being compiled won't link against any ID shared
8934 libraries. Slower code will be generated for jump and call insns.
8936 @item -mshared-library-id=n
8937 @opindex mshared-library-id
8938 Specified the identification number of the ID based shared library being
8939 compiled. Specifying a value of 0 will generate more compact code, specifying
8940 other values will force the allocation of that number to the current
8941 library but is no more space or time efficient than omitting this option.
8945 Generate code that allows the data segment to be located in a different
8946 area of memory from the text segment. This allows for execute in place in
8947 an environment without virtual memory management by eliminating relocations
8948 against the text section.
8951 @opindex mno-sep-data
8952 Generate code that assumes that the data segment follows the text segment.
8953 This is the default.
8956 @itemx -mno-long-calls
8957 @opindex mlong-calls
8958 @opindex mno-long-calls
8959 Tells the compiler to perform function calls by first loading the
8960 address of the function into a register and then performing a subroutine
8961 call on this register. This switch is needed if the target function
8962 will lie outside of the 24 bit addressing range of the offset based
8963 version of subroutine call instruction.
8965 This feature is not enabled by default. Specifying
8966 @option{-mno-long-calls} will restore the default behavior. Note these
8967 switches have no effect on how the compiler generates code to handle
8968 function calls via function pointers.
8972 Link with the fast floating-point library. This library relaxes some of
8973 the IEEE floating-point standard's rules for checking inputs against
8974 Not-a-Number (NAN), in the interest of performance.
8977 @opindex minline-plt
8978 Enable inlining of PLT entries in function calls to functions that are
8979 not known to bind locally. It has no effect without @option{-mfdpic}.
8983 @subsection CRIS Options
8984 @cindex CRIS Options
8986 These options are defined specifically for the CRIS ports.
8989 @item -march=@var{architecture-type}
8990 @itemx -mcpu=@var{architecture-type}
8993 Generate code for the specified architecture. The choices for
8994 @var{architecture-type} are @samp{v3}, @samp{v8} and @samp{v10} for
8995 respectively ETRAX@w{ }4, ETRAX@w{ }100, and ETRAX@w{ }100@w{ }LX@.
8996 Default is @samp{v0} except for cris-axis-linux-gnu, where the default is
8999 @item -mtune=@var{architecture-type}
9001 Tune to @var{architecture-type} everything applicable about the generated
9002 code, except for the ABI and the set of available instructions. The
9003 choices for @var{architecture-type} are the same as for
9004 @option{-march=@var{architecture-type}}.
9006 @item -mmax-stack-frame=@var{n}
9007 @opindex mmax-stack-frame
9008 Warn when the stack frame of a function exceeds @var{n} bytes.
9010 @item -melinux-stacksize=@var{n}
9011 @opindex melinux-stacksize
9012 Only available with the @samp{cris-axis-aout} target. Arranges for
9013 indications in the program to the kernel loader that the stack of the
9014 program should be set to @var{n} bytes.
9020 The options @option{-metrax4} and @option{-metrax100} are synonyms for
9021 @option{-march=v3} and @option{-march=v8} respectively.
9023 @item -mmul-bug-workaround
9024 @itemx -mno-mul-bug-workaround
9025 @opindex mmul-bug-workaround
9026 @opindex mno-mul-bug-workaround
9027 Work around a bug in the @code{muls} and @code{mulu} instructions for CPU
9028 models where it applies. This option is active by default.
9032 Enable CRIS-specific verbose debug-related information in the assembly
9033 code. This option also has the effect to turn off the @samp{#NO_APP}
9034 formatted-code indicator to the assembler at the beginning of the
9039 Do not use condition-code results from previous instruction; always emit
9040 compare and test instructions before use of condition codes.
9042 @item -mno-side-effects
9043 @opindex mno-side-effects
9044 Do not emit instructions with side-effects in addressing modes other than
9048 @itemx -mno-stack-align
9050 @itemx -mno-data-align
9051 @itemx -mconst-align
9052 @itemx -mno-const-align
9053 @opindex mstack-align
9054 @opindex mno-stack-align
9055 @opindex mdata-align
9056 @opindex mno-data-align
9057 @opindex mconst-align
9058 @opindex mno-const-align
9059 These options (no-options) arranges (eliminate arrangements) for the
9060 stack-frame, individual data and constants to be aligned for the maximum
9061 single data access size for the chosen CPU model. The default is to
9062 arrange for 32-bit alignment. ABI details such as structure layout are
9063 not affected by these options.
9071 Similar to the stack- data- and const-align options above, these options
9072 arrange for stack-frame, writable data and constants to all be 32-bit,
9073 16-bit or 8-bit aligned. The default is 32-bit alignment.
9075 @item -mno-prologue-epilogue
9076 @itemx -mprologue-epilogue
9077 @opindex mno-prologue-epilogue
9078 @opindex mprologue-epilogue
9079 With @option{-mno-prologue-epilogue}, the normal function prologue and
9080 epilogue that sets up the stack-frame are omitted and no return
9081 instructions or return sequences are generated in the code. Use this
9082 option only together with visual inspection of the compiled code: no
9083 warnings or errors are generated when call-saved registers must be saved,
9084 or storage for local variable needs to be allocated.
9090 With @option{-fpic} and @option{-fPIC}, don't generate (do generate)
9091 instruction sequences that load addresses for functions from the PLT part
9092 of the GOT rather than (traditional on other architectures) calls to the
9093 PLT@. The default is @option{-mgotplt}.
9097 Legacy no-op option only recognized with the cris-axis-aout target.
9101 Legacy no-op option only recognized with the cris-axis-elf and
9102 cris-axis-linux-gnu targets.
9106 Only recognized with the cris-axis-aout target, where it selects a
9107 GNU/linux-like multilib, include files and instruction set for
9112 Legacy no-op option only recognized with the cris-axis-linux-gnu target.
9116 This option, recognized for the cris-axis-aout and cris-axis-elf arranges
9117 to link with input-output functions from a simulator library. Code,
9118 initialized data and zero-initialized data are allocated consecutively.
9122 Like @option{-sim}, but pass linker options to locate initialized data at
9123 0x40000000 and zero-initialized data at 0x80000000.
9127 @subsection CRX Options
9130 These options are defined specifically for the CRX ports.
9136 Enable the use of multiply-accumulate instructions. Disabled by default.
9140 Push instructions will be used to pass outgoing arguments when functions
9141 are called. Enabled by default.
9144 @node Darwin Options
9145 @subsection Darwin Options
9146 @cindex Darwin options
9148 These options are defined for all architectures running the Darwin operating
9151 FSF GCC on Darwin does not create ``fat'' object files; it will create
9152 an object file for the single architecture that it was built to
9153 target. Apple's GCC on Darwin does create ``fat'' files if multiple
9154 @option{-arch} options are used; it does so by running the compiler or
9155 linker multiple times and joining the results together with
9158 The subtype of the file created (like @samp{ppc7400} or @samp{ppc970} or
9159 @samp{i686}) is determined by the flags that specify the ISA
9160 that GCC is targetting, like @option{-mcpu} or @option{-march}. The
9161 @option{-force_cpusubtype_ALL} option can be used to override this.
9163 The Darwin tools vary in their behavior when presented with an ISA
9164 mismatch. The assembler, @file{as}, will only permit instructions to
9165 be used that are valid for the subtype of the file it is generating,
9166 so you cannot put 64-bit instructions in an @samp{ppc750} object file.
9167 The linker for shared libraries, @file{/usr/bin/libtool}, will fail
9168 and print an error if asked to create a shared library with a less
9169 restrictive subtype than its input files (for instance, trying to put
9170 a @samp{ppc970} object file in a @samp{ppc7400} library). The linker
9171 for executables, @file{ld}, will quietly give the executable the most
9172 restrictive subtype of any of its input files.
9177 Add the framework directory @var{dir} to the head of the list of
9178 directories to be searched for header files. These directories are
9179 interleaved with those specified by @option{-I} options and are
9180 scanned in a left-to-right order.
9182 A framework directory is a directory with frameworks in it. A
9183 framework is a directory with a @samp{"Headers"} and/or
9184 @samp{"PrivateHeaders"} directory contained directly in it that ends
9185 in @samp{".framework"}. The name of a framework is the name of this
9186 directory excluding the @samp{".framework"}. Headers associated with
9187 the framework are found in one of those two directories, with
9188 @samp{"Headers"} being searched first. A subframework is a framework
9189 directory that is in a framework's @samp{"Frameworks"} directory.
9190 Includes of subframework headers can only appear in a header of a
9191 framework that contains the subframework, or in a sibling subframework
9192 header. Two subframeworks are siblings if they occur in the same
9193 framework. A subframework should not have the same name as a
9194 framework, a warning will be issued if this is violated. Currently a
9195 subframework cannot have subframeworks, in the future, the mechanism
9196 may be extended to support this. The standard frameworks can be found
9197 in @samp{"/System/Library/Frameworks"} and
9198 @samp{"/Library/Frameworks"}. An example include looks like
9199 @code{#include <Framework/header.h>}, where @samp{Framework} denotes
9200 the name of the framework and header.h is found in the
9201 @samp{"PrivateHeaders"} or @samp{"Headers"} directory.
9203 @item -iframework@var{dir}
9205 Like @option{-F} except the directory is a treated as a system
9206 directory. The main difference between this @option{-iframework} and
9207 @option{-F} is that with @option{-iframework} the compiler does not
9208 warn about constructs contained within header files found via
9209 @var{dir}. This option is valid only for the C family of languages.
9213 Emit debugging information for symbols that are used. For STABS
9214 debugging format, this enables @option{-feliminate-unused-debug-symbols}.
9215 This is by default ON@.
9219 Emit debugging information for all symbols and types.
9221 @item -mmacosx-version-min=@var{version}
9222 The earliest version of MacOS X that this executable will run on
9223 is @var{version}. Typical values of @var{version} include @code{10.1},
9224 @code{10.2}, and @code{10.3.9}.
9226 If the compiler was built to use the system's headers by default,
9227 then the default for this option is the system version on which the
9228 compiler is running, otherwise the default is to make choices which
9229 are compatible with as many systems and code bases as possible.
9233 Enable kernel development mode. The @option{-mkernel} option sets
9234 @option{-static}, @option{-fno-common}, @option{-fno-cxa-atexit},
9235 @option{-fno-exceptions}, @option{-fno-non-call-exceptions},
9236 @option{-fapple-kext}, @option{-fno-weak} and @option{-fno-rtti} where
9237 applicable. This mode also sets @option{-mno-altivec},
9238 @option{-msoft-float}, @option{-fno-builtin} and
9239 @option{-mlong-branch} for PowerPC targets.
9241 @item -mone-byte-bool
9242 @opindex mone-byte-bool
9243 Override the defaults for @samp{bool} so that @samp{sizeof(bool)==1}.
9244 By default @samp{sizeof(bool)} is @samp{4} when compiling for
9245 Darwin/PowerPC and @samp{1} when compiling for Darwin/x86, so this
9246 option has no effect on x86.
9248 @strong{Warning:} The @option{-mone-byte-bool} switch causes GCC
9249 to generate code that is not binary compatible with code generated
9250 without that switch. Using this switch may require recompiling all
9251 other modules in a program, including system libraries. Use this
9252 switch to conform to a non-default data model.
9254 @item -mfix-and-continue
9255 @itemx -ffix-and-continue
9256 @itemx -findirect-data
9257 @opindex mfix-and-continue
9258 @opindex ffix-and-continue
9259 @opindex findirect-data
9260 Generate code suitable for fast turn around development. Needed to
9261 enable gdb to dynamically load @code{.o} files into already running
9262 programs. @option{-findirect-data} and @option{-ffix-and-continue}
9263 are provided for backwards compatibility.
9267 Loads all members of static archive libraries.
9268 See man ld(1) for more information.
9270 @item -arch_errors_fatal
9271 @opindex arch_errors_fatal
9272 Cause the errors having to do with files that have the wrong architecture
9276 @opindex bind_at_load
9277 Causes the output file to be marked such that the dynamic linker will
9278 bind all undefined references when the file is loaded or launched.
9282 Produce a Mach-o bundle format file.
9283 See man ld(1) for more information.
9285 @item -bundle_loader @var{executable}
9286 @opindex bundle_loader
9287 This option specifies the @var{executable} that will be loading the build
9288 output file being linked. See man ld(1) for more information.
9292 When passed this option, GCC will produce a dynamic library instead of
9293 an executable when linking, using the Darwin @file{libtool} command.
9295 @item -force_cpusubtype_ALL
9296 @opindex force_cpusubtype_ALL
9297 This causes GCC's output file to have the @var{ALL} subtype, instead of
9298 one controlled by the @option{-mcpu} or @option{-march} option.
9300 @item -allowable_client @var{client_name}
9302 @itemx -compatibility_version
9303 @itemx -current_version
9305 @itemx -dependency-file
9307 @itemx -dylinker_install_name
9309 @itemx -exported_symbols_list
9311 @itemx -flat_namespace
9312 @itemx -force_flat_namespace
9313 @itemx -headerpad_max_install_names
9316 @itemx -install_name
9317 @itemx -keep_private_externs
9318 @itemx -multi_module
9319 @itemx -multiply_defined
9320 @itemx -multiply_defined_unused
9322 @itemx -no_dead_strip_inits_and_terms
9323 @itemx -nofixprebinding
9326 @itemx -noseglinkedit
9327 @itemx -pagezero_size
9329 @itemx -prebind_all_twolevel_modules
9330 @itemx -private_bundle
9331 @itemx -read_only_relocs
9333 @itemx -sectobjectsymbols
9337 @itemx -sectobjectsymbols
9340 @itemx -segs_read_only_addr
9341 @itemx -segs_read_write_addr
9342 @itemx -seg_addr_table
9343 @itemx -seg_addr_table_filename
9346 @itemx -segs_read_only_addr
9347 @itemx -segs_read_write_addr
9348 @itemx -single_module
9351 @itemx -sub_umbrella
9352 @itemx -twolevel_namespace
9355 @itemx -unexported_symbols_list
9356 @itemx -weak_reference_mismatches
9359 @opindex allowable_client
9360 @opindex client_name
9361 @opindex compatibility_version
9362 @opindex current_version
9364 @opindex dependency-file
9366 @opindex dylinker_install_name
9368 @opindex exported_symbols_list
9370 @opindex flat_namespace
9371 @opindex force_flat_namespace
9372 @opindex headerpad_max_install_names
9375 @opindex install_name
9376 @opindex keep_private_externs
9377 @opindex multi_module
9378 @opindex multiply_defined
9379 @opindex multiply_defined_unused
9381 @opindex no_dead_strip_inits_and_terms
9382 @opindex nofixprebinding
9383 @opindex nomultidefs
9385 @opindex noseglinkedit
9386 @opindex pagezero_size
9388 @opindex prebind_all_twolevel_modules
9389 @opindex private_bundle
9390 @opindex read_only_relocs
9392 @opindex sectobjectsymbols
9396 @opindex sectobjectsymbols
9399 @opindex segs_read_only_addr
9400 @opindex segs_read_write_addr
9401 @opindex seg_addr_table
9402 @opindex seg_addr_table_filename
9403 @opindex seglinkedit
9405 @opindex segs_read_only_addr
9406 @opindex segs_read_write_addr
9407 @opindex single_module
9409 @opindex sub_library
9410 @opindex sub_umbrella
9411 @opindex twolevel_namespace
9414 @opindex unexported_symbols_list
9415 @opindex weak_reference_mismatches
9416 @opindex whatsloaded
9418 These options are passed to the Darwin linker. The Darwin linker man page
9419 describes them in detail.
9422 @node DEC Alpha Options
9423 @subsection DEC Alpha Options
9425 These @samp{-m} options are defined for the DEC Alpha implementations:
9428 @item -mno-soft-float
9430 @opindex mno-soft-float
9431 @opindex msoft-float
9432 Use (do not use) the hardware floating-point instructions for
9433 floating-point operations. When @option{-msoft-float} is specified,
9434 functions in @file{libgcc.a} will be used to perform floating-point
9435 operations. Unless they are replaced by routines that emulate the
9436 floating-point operations, or compiled in such a way as to call such
9437 emulations routines, these routines will issue floating-point
9438 operations. If you are compiling for an Alpha without floating-point
9439 operations, you must ensure that the library is built so as not to call
9442 Note that Alpha implementations without floating-point operations are
9443 required to have floating-point registers.
9448 @opindex mno-fp-regs
9449 Generate code that uses (does not use) the floating-point register set.
9450 @option{-mno-fp-regs} implies @option{-msoft-float}. If the floating-point
9451 register set is not used, floating point operands are passed in integer
9452 registers as if they were integers and floating-point results are passed
9453 in @code{$0} instead of @code{$f0}. This is a non-standard calling sequence,
9454 so any function with a floating-point argument or return value called by code
9455 compiled with @option{-mno-fp-regs} must also be compiled with that
9458 A typical use of this option is building a kernel that does not use,
9459 and hence need not save and restore, any floating-point registers.
9463 The Alpha architecture implements floating-point hardware optimized for
9464 maximum performance. It is mostly compliant with the IEEE floating
9465 point standard. However, for full compliance, software assistance is
9466 required. This option generates code fully IEEE compliant code
9467 @emph{except} that the @var{inexact-flag} is not maintained (see below).
9468 If this option is turned on, the preprocessor macro @code{_IEEE_FP} is
9469 defined during compilation. The resulting code is less efficient but is
9470 able to correctly support denormalized numbers and exceptional IEEE
9471 values such as not-a-number and plus/minus infinity. Other Alpha
9472 compilers call this option @option{-ieee_with_no_inexact}.
9474 @item -mieee-with-inexact
9475 @opindex mieee-with-inexact
9476 This is like @option{-mieee} except the generated code also maintains
9477 the IEEE @var{inexact-flag}. Turning on this option causes the
9478 generated code to implement fully-compliant IEEE math. In addition to
9479 @code{_IEEE_FP}, @code{_IEEE_FP_EXACT} is defined as a preprocessor
9480 macro. On some Alpha implementations the resulting code may execute
9481 significantly slower than the code generated by default. Since there is
9482 very little code that depends on the @var{inexact-flag}, you should
9483 normally not specify this option. Other Alpha compilers call this
9484 option @option{-ieee_with_inexact}.
9486 @item -mfp-trap-mode=@var{trap-mode}
9487 @opindex mfp-trap-mode
9488 This option controls what floating-point related traps are enabled.
9489 Other Alpha compilers call this option @option{-fptm @var{trap-mode}}.
9490 The trap mode can be set to one of four values:
9494 This is the default (normal) setting. The only traps that are enabled
9495 are the ones that cannot be disabled in software (e.g., division by zero
9499 In addition to the traps enabled by @samp{n}, underflow traps are enabled
9503 Like @samp{u}, but the instructions are marked to be safe for software
9504 completion (see Alpha architecture manual for details).
9507 Like @samp{su}, but inexact traps are enabled as well.
9510 @item -mfp-rounding-mode=@var{rounding-mode}
9511 @opindex mfp-rounding-mode
9512 Selects the IEEE rounding mode. Other Alpha compilers call this option
9513 @option{-fprm @var{rounding-mode}}. The @var{rounding-mode} can be one
9518 Normal IEEE rounding mode. Floating point numbers are rounded towards
9519 the nearest machine number or towards the even machine number in case
9523 Round towards minus infinity.
9526 Chopped rounding mode. Floating point numbers are rounded towards zero.
9529 Dynamic rounding mode. A field in the floating point control register
9530 (@var{fpcr}, see Alpha architecture reference manual) controls the
9531 rounding mode in effect. The C library initializes this register for
9532 rounding towards plus infinity. Thus, unless your program modifies the
9533 @var{fpcr}, @samp{d} corresponds to round towards plus infinity.
9536 @item -mtrap-precision=@var{trap-precision}
9537 @opindex mtrap-precision
9538 In the Alpha architecture, floating point traps are imprecise. This
9539 means without software assistance it is impossible to recover from a
9540 floating trap and program execution normally needs to be terminated.
9541 GCC can generate code that can assist operating system trap handlers
9542 in determining the exact location that caused a floating point trap.
9543 Depending on the requirements of an application, different levels of
9544 precisions can be selected:
9548 Program precision. This option is the default and means a trap handler
9549 can only identify which program caused a floating point exception.
9552 Function precision. The trap handler can determine the function that
9553 caused a floating point exception.
9556 Instruction precision. The trap handler can determine the exact
9557 instruction that caused a floating point exception.
9560 Other Alpha compilers provide the equivalent options called
9561 @option{-scope_safe} and @option{-resumption_safe}.
9563 @item -mieee-conformant
9564 @opindex mieee-conformant
9565 This option marks the generated code as IEEE conformant. You must not
9566 use this option unless you also specify @option{-mtrap-precision=i} and either
9567 @option{-mfp-trap-mode=su} or @option{-mfp-trap-mode=sui}. Its only effect
9568 is to emit the line @samp{.eflag 48} in the function prologue of the
9569 generated assembly file. Under DEC Unix, this has the effect that
9570 IEEE-conformant math library routines will be linked in.
9572 @item -mbuild-constants
9573 @opindex mbuild-constants
9574 Normally GCC examines a 32- or 64-bit integer constant to
9575 see if it can construct it from smaller constants in two or three
9576 instructions. If it cannot, it will output the constant as a literal and
9577 generate code to load it from the data segment at runtime.
9579 Use this option to require GCC to construct @emph{all} integer constants
9580 using code, even if it takes more instructions (the maximum is six).
9582 You would typically use this option to build a shared library dynamic
9583 loader. Itself a shared library, it must relocate itself in memory
9584 before it can find the variables and constants in its own data segment.
9590 Select whether to generate code to be assembled by the vendor-supplied
9591 assembler (@option{-malpha-as}) or by the GNU assembler @option{-mgas}.
9609 Indicate whether GCC should generate code to use the optional BWX,
9610 CIX, FIX and MAX instruction sets. The default is to use the instruction
9611 sets supported by the CPU type specified via @option{-mcpu=} option or that
9612 of the CPU on which GCC was built if none was specified.
9617 @opindex mfloat-ieee
9618 Generate code that uses (does not use) VAX F and G floating point
9619 arithmetic instead of IEEE single and double precision.
9621 @item -mexplicit-relocs
9622 @itemx -mno-explicit-relocs
9623 @opindex mexplicit-relocs
9624 @opindex mno-explicit-relocs
9625 Older Alpha assemblers provided no way to generate symbol relocations
9626 except via assembler macros. Use of these macros does not allow
9627 optimal instruction scheduling. GNU binutils as of version 2.12
9628 supports a new syntax that allows the compiler to explicitly mark
9629 which relocations should apply to which instructions. This option
9630 is mostly useful for debugging, as GCC detects the capabilities of
9631 the assembler when it is built and sets the default accordingly.
9635 @opindex msmall-data
9636 @opindex mlarge-data
9637 When @option{-mexplicit-relocs} is in effect, static data is
9638 accessed via @dfn{gp-relative} relocations. When @option{-msmall-data}
9639 is used, objects 8 bytes long or smaller are placed in a @dfn{small data area}
9640 (the @code{.sdata} and @code{.sbss} sections) and are accessed via
9641 16-bit relocations off of the @code{$gp} register. This limits the
9642 size of the small data area to 64KB, but allows the variables to be
9643 directly accessed via a single instruction.
9645 The default is @option{-mlarge-data}. With this option the data area
9646 is limited to just below 2GB@. Programs that require more than 2GB of
9647 data must use @code{malloc} or @code{mmap} to allocate the data in the
9648 heap instead of in the program's data segment.
9650 When generating code for shared libraries, @option{-fpic} implies
9651 @option{-msmall-data} and @option{-fPIC} implies @option{-mlarge-data}.
9655 @opindex msmall-text
9656 @opindex mlarge-text
9657 When @option{-msmall-text} is used, the compiler assumes that the
9658 code of the entire program (or shared library) fits in 4MB, and is
9659 thus reachable with a branch instruction. When @option{-msmall-data}
9660 is used, the compiler can assume that all local symbols share the
9661 same @code{$gp} value, and thus reduce the number of instructions
9662 required for a function call from 4 to 1.
9664 The default is @option{-mlarge-text}.
9666 @item -mcpu=@var{cpu_type}
9668 Set the instruction set and instruction scheduling parameters for
9669 machine type @var{cpu_type}. You can specify either the @samp{EV}
9670 style name or the corresponding chip number. GCC supports scheduling
9671 parameters for the EV4, EV5 and EV6 family of processors and will
9672 choose the default values for the instruction set from the processor
9673 you specify. If you do not specify a processor type, GCC will default
9674 to the processor on which the compiler was built.
9676 Supported values for @var{cpu_type} are
9682 Schedules as an EV4 and has no instruction set extensions.
9686 Schedules as an EV5 and has no instruction set extensions.
9690 Schedules as an EV5 and supports the BWX extension.
9695 Schedules as an EV5 and supports the BWX and MAX extensions.
9699 Schedules as an EV6 and supports the BWX, FIX, and MAX extensions.
9703 Schedules as an EV6 and supports the BWX, CIX, FIX, and MAX extensions.
9706 @item -mtune=@var{cpu_type}
9708 Set only the instruction scheduling parameters for machine type
9709 @var{cpu_type}. The instruction set is not changed.
9711 @item -mmemory-latency=@var{time}
9712 @opindex mmemory-latency
9713 Sets the latency the scheduler should assume for typical memory
9714 references as seen by the application. This number is highly
9715 dependent on the memory access patterns used by the application
9716 and the size of the external cache on the machine.
9718 Valid options for @var{time} are
9722 A decimal number representing clock cycles.
9728 The compiler contains estimates of the number of clock cycles for
9729 ``typical'' EV4 & EV5 hardware for the Level 1, 2 & 3 caches
9730 (also called Dcache, Scache, and Bcache), as well as to main memory.
9731 Note that L3 is only valid for EV5.
9736 @node DEC Alpha/VMS Options
9737 @subsection DEC Alpha/VMS Options
9739 These @samp{-m} options are defined for the DEC Alpha/VMS implementations:
9742 @item -mvms-return-codes
9743 @opindex mvms-return-codes
9744 Return VMS condition codes from main. The default is to return POSIX
9745 style condition (e.g.@: error) codes.
9749 @subsection FRV Options
9756 Only use the first 32 general purpose registers.
9761 Use all 64 general purpose registers.
9766 Use only the first 32 floating point registers.
9771 Use all 64 floating point registers
9774 @opindex mhard-float
9776 Use hardware instructions for floating point operations.
9779 @opindex msoft-float
9781 Use library routines for floating point operations.
9786 Dynamically allocate condition code registers.
9791 Do not try to dynamically allocate condition code registers, only
9792 use @code{icc0} and @code{fcc0}.
9797 Change ABI to use double word insns.
9802 Do not use double word instructions.
9807 Use floating point double instructions.
9812 Do not use floating point double instructions.
9817 Use media instructions.
9822 Do not use media instructions.
9827 Use multiply and add/subtract instructions.
9832 Do not use multiply and add/subtract instructions.
9837 Select the FDPIC ABI, that uses function descriptors to represent
9838 pointers to functions. Without any PIC/PIE-related options, it
9839 implies @option{-fPIE}. With @option{-fpic} or @option{-fpie}, it
9840 assumes GOT entries and small data are within a 12-bit range from the
9841 GOT base address; with @option{-fPIC} or @option{-fPIE}, GOT offsets
9842 are computed with 32 bits.
9843 With a @samp{bfin-elf} target, this option implies @option{-msim}.
9846 @opindex minline-plt
9848 Enable inlining of PLT entries in function calls to functions that are
9849 not known to bind locally. It has no effect without @option{-mfdpic}.
9850 It's enabled by default if optimizing for speed and compiling for
9851 shared libraries (i.e., @option{-fPIC} or @option{-fpic}), or when an
9852 optimization option such as @option{-O3} or above is present in the
9858 Assume a large TLS segment when generating thread-local code.
9863 Do not assume a large TLS segment when generating thread-local code.
9868 Enable the use of @code{GPREL} relocations in the FDPIC ABI for data
9869 that is known to be in read-only sections. It's enabled by default,
9870 except for @option{-fpic} or @option{-fpie}: even though it may help
9871 make the global offset table smaller, it trades 1 instruction for 4.
9872 With @option{-fPIC} or @option{-fPIE}, it trades 3 instructions for 4,
9873 one of which may be shared by multiple symbols, and it avoids the need
9874 for a GOT entry for the referenced symbol, so it's more likely to be a
9875 win. If it is not, @option{-mno-gprel-ro} can be used to disable it.
9877 @item -multilib-library-pic
9878 @opindex multilib-library-pic
9880 Link with the (library, not FD) pic libraries. It's implied by
9881 @option{-mlibrary-pic}, as well as by @option{-fPIC} and
9882 @option{-fpic} without @option{-mfdpic}. You should never have to use
9888 Follow the EABI requirement of always creating a frame pointer whenever
9889 a stack frame is allocated. This option is enabled by default and can
9890 be disabled with @option{-mno-linked-fp}.
9893 @opindex mlong-calls
9895 Use indirect addressing to call functions outside the current
9896 compilation unit. This allows the functions to be placed anywhere
9897 within the 32-bit address space.
9899 @item -malign-labels
9900 @opindex malign-labels
9902 Try to align labels to an 8-byte boundary by inserting nops into the
9903 previous packet. This option only has an effect when VLIW packing
9904 is enabled. It doesn't create new packets; it merely adds nops to
9908 @opindex mlibrary-pic
9910 Generate position-independent EABI code.
9915 Use only the first four media accumulator registers.
9920 Use all eight media accumulator registers.
9925 Pack VLIW instructions.
9930 Do not pack VLIW instructions.
9935 Do not mark ABI switches in e_flags.
9940 Enable the use of conditional-move instructions (default).
9942 This switch is mainly for debugging the compiler and will likely be removed
9943 in a future version.
9945 @item -mno-cond-move
9946 @opindex mno-cond-move
9948 Disable the use of conditional-move instructions.
9950 This switch is mainly for debugging the compiler and will likely be removed
9951 in a future version.
9956 Enable the use of conditional set instructions (default).
9958 This switch is mainly for debugging the compiler and will likely be removed
9959 in a future version.
9964 Disable the use of conditional set instructions.
9966 This switch is mainly for debugging the compiler and will likely be removed
9967 in a future version.
9972 Enable the use of conditional execution (default).
9974 This switch is mainly for debugging the compiler and will likely be removed
9975 in a future version.
9977 @item -mno-cond-exec
9978 @opindex mno-cond-exec
9980 Disable the use of conditional execution.
9982 This switch is mainly for debugging the compiler and will likely be removed
9983 in a future version.
9986 @opindex mvliw-branch
9988 Run a pass to pack branches into VLIW instructions (default).
9990 This switch is mainly for debugging the compiler and will likely be removed
9991 in a future version.
9993 @item -mno-vliw-branch
9994 @opindex mno-vliw-branch
9996 Do not run a pass to pack branches into VLIW instructions.
9998 This switch is mainly for debugging the compiler and will likely be removed
9999 in a future version.
10001 @item -mmulti-cond-exec
10002 @opindex mmulti-cond-exec
10004 Enable optimization of @code{&&} and @code{||} in conditional execution
10007 This switch is mainly for debugging the compiler and will likely be removed
10008 in a future version.
10010 @item -mno-multi-cond-exec
10011 @opindex mno-multi-cond-exec
10013 Disable optimization of @code{&&} and @code{||} in conditional execution.
10015 This switch is mainly for debugging the compiler and will likely be removed
10016 in a future version.
10018 @item -mnested-cond-exec
10019 @opindex mnested-cond-exec
10021 Enable nested conditional execution optimizations (default).
10023 This switch is mainly for debugging the compiler and will likely be removed
10024 in a future version.
10026 @item -mno-nested-cond-exec
10027 @opindex mno-nested-cond-exec
10029 Disable nested conditional execution optimizations.
10031 This switch is mainly for debugging the compiler and will likely be removed
10032 in a future version.
10034 @item -moptimize-membar
10035 @opindex moptimize-membar
10037 This switch removes redundant @code{membar} instructions from the
10038 compiler generated code. It is enabled by default.
10040 @item -mno-optimize-membar
10041 @opindex mno-optimize-membar
10043 This switch disables the automatic removal of redundant @code{membar}
10044 instructions from the generated code.
10046 @item -mtomcat-stats
10047 @opindex mtomcat-stats
10049 Cause gas to print out tomcat statistics.
10051 @item -mcpu=@var{cpu}
10054 Select the processor type for which to generate code. Possible values are
10055 @samp{frv}, @samp{fr550}, @samp{tomcat}, @samp{fr500}, @samp{fr450},
10056 @samp{fr405}, @samp{fr400}, @samp{fr300} and @samp{simple}.
10060 @node GNU/Linux Options
10061 @subsection GNU/Linux Options
10063 These @samp{-m} options are defined for GNU/Linux targets:
10068 Use the GNU C library instead of uClibc. This is the default except
10069 on @samp{*-*-linux-*uclibc*} targets.
10073 Use uClibc instead of the GNU C library. This is the default on
10074 @samp{*-*-linux-*uclibc*} targets.
10077 @node H8/300 Options
10078 @subsection H8/300 Options
10080 These @samp{-m} options are defined for the H8/300 implementations:
10085 Shorten some address references at link time, when possible; uses the
10086 linker option @option{-relax}. @xref{H8/300,, @code{ld} and the H8/300,
10087 ld, Using ld}, for a fuller description.
10091 Generate code for the H8/300H@.
10095 Generate code for the H8S@.
10099 Generate code for the H8S and H8/300H in the normal mode. This switch
10100 must be used either with @option{-mh} or @option{-ms}.
10104 Generate code for the H8S/2600. This switch must be used with @option{-ms}.
10108 Make @code{int} data 32 bits by default.
10111 @opindex malign-300
10112 On the H8/300H and H8S, use the same alignment rules as for the H8/300.
10113 The default for the H8/300H and H8S is to align longs and floats on 4
10115 @option{-malign-300} causes them to be aligned on 2 byte boundaries.
10116 This option has no effect on the H8/300.
10120 @subsection HPPA Options
10121 @cindex HPPA Options
10123 These @samp{-m} options are defined for the HPPA family of computers:
10126 @item -march=@var{architecture-type}
10128 Generate code for the specified architecture. The choices for
10129 @var{architecture-type} are @samp{1.0} for PA 1.0, @samp{1.1} for PA
10130 1.1, and @samp{2.0} for PA 2.0 processors. Refer to
10131 @file{/usr/lib/sched.models} on an HP-UX system to determine the proper
10132 architecture option for your machine. Code compiled for lower numbered
10133 architectures will run on higher numbered architectures, but not the
10136 @item -mpa-risc-1-0
10137 @itemx -mpa-risc-1-1
10138 @itemx -mpa-risc-2-0
10139 @opindex mpa-risc-1-0
10140 @opindex mpa-risc-1-1
10141 @opindex mpa-risc-2-0
10142 Synonyms for @option{-march=1.0}, @option{-march=1.1}, and @option{-march=2.0} respectively.
10145 @opindex mbig-switch
10146 Generate code suitable for big switch tables. Use this option only if
10147 the assembler/linker complain about out of range branches within a switch
10150 @item -mjump-in-delay
10151 @opindex mjump-in-delay
10152 Fill delay slots of function calls with unconditional jump instructions
10153 by modifying the return pointer for the function call to be the target
10154 of the conditional jump.
10156 @item -mdisable-fpregs
10157 @opindex mdisable-fpregs
10158 Prevent floating point registers from being used in any manner. This is
10159 necessary for compiling kernels which perform lazy context switching of
10160 floating point registers. If you use this option and attempt to perform
10161 floating point operations, the compiler will abort.
10163 @item -mdisable-indexing
10164 @opindex mdisable-indexing
10165 Prevent the compiler from using indexing address modes. This avoids some
10166 rather obscure problems when compiling MIG generated code under MACH@.
10168 @item -mno-space-regs
10169 @opindex mno-space-regs
10170 Generate code that assumes the target has no space registers. This allows
10171 GCC to generate faster indirect calls and use unscaled index address modes.
10173 Such code is suitable for level 0 PA systems and kernels.
10175 @item -mfast-indirect-calls
10176 @opindex mfast-indirect-calls
10177 Generate code that assumes calls never cross space boundaries. This
10178 allows GCC to emit code which performs faster indirect calls.
10180 This option will not work in the presence of shared libraries or nested
10183 @item -mfixed-range=@var{register-range}
10184 @opindex mfixed-range
10185 Generate code treating the given register range as fixed registers.
10186 A fixed register is one that the register allocator can not use. This is
10187 useful when compiling kernel code. A register range is specified as
10188 two registers separated by a dash. Multiple register ranges can be
10189 specified separated by a comma.
10191 @item -mlong-load-store
10192 @opindex mlong-load-store
10193 Generate 3-instruction load and store sequences as sometimes required by
10194 the HP-UX 10 linker. This is equivalent to the @samp{+k} option to
10197 @item -mportable-runtime
10198 @opindex mportable-runtime
10199 Use the portable calling conventions proposed by HP for ELF systems.
10203 Enable the use of assembler directives only GAS understands.
10205 @item -mschedule=@var{cpu-type}
10207 Schedule code according to the constraints for the machine type
10208 @var{cpu-type}. The choices for @var{cpu-type} are @samp{700}
10209 @samp{7100}, @samp{7100LC}, @samp{7200}, @samp{7300} and @samp{8000}. Refer
10210 to @file{/usr/lib/sched.models} on an HP-UX system to determine the
10211 proper scheduling option for your machine. The default scheduling is
10215 @opindex mlinker-opt
10216 Enable the optimization pass in the HP-UX linker. Note this makes symbolic
10217 debugging impossible. It also triggers a bug in the HP-UX 8 and HP-UX 9
10218 linkers in which they give bogus error messages when linking some programs.
10221 @opindex msoft-float
10222 Generate output containing library calls for floating point.
10223 @strong{Warning:} the requisite libraries are not available for all HPPA
10224 targets. Normally the facilities of the machine's usual C compiler are
10225 used, but this cannot be done directly in cross-compilation. You must make
10226 your own arrangements to provide suitable library functions for
10227 cross-compilation. The embedded target @samp{hppa1.1-*-pro}
10228 does provide software floating point support.
10230 @option{-msoft-float} changes the calling convention in the output file;
10231 therefore, it is only useful if you compile @emph{all} of a program with
10232 this option. In particular, you need to compile @file{libgcc.a}, the
10233 library that comes with GCC, with @option{-msoft-float} in order for
10238 Generate the predefine, @code{_SIO}, for server IO@. The default is
10239 @option{-mwsio}. This generates the predefines, @code{__hp9000s700},
10240 @code{__hp9000s700__} and @code{_WSIO}, for workstation IO@. These
10241 options are available under HP-UX and HI-UX@.
10245 Use GNU ld specific options. This passes @option{-shared} to ld when
10246 building a shared library. It is the default when GCC is configured,
10247 explicitly or implicitly, with the GNU linker. This option does not
10248 have any affect on which ld is called, it only changes what parameters
10249 are passed to that ld. The ld that is called is determined by the
10250 @option{--with-ld} configure option, GCC's program search path, and
10251 finally by the user's @env{PATH}. The linker used by GCC can be printed
10252 using @samp{which `gcc -print-prog-name=ld`}. This option is only available
10253 on the 64 bit HP-UX GCC, i.e.@: configured with @samp{hppa*64*-*-hpux*}.
10257 Use HP ld specific options. This passes @option{-b} to ld when building
10258 a shared library and passes @option{+Accept TypeMismatch} to ld on all
10259 links. It is the default when GCC is configured, explicitly or
10260 implicitly, with the HP linker. This option does not have any affect on
10261 which ld is called, it only changes what parameters are passed to that
10262 ld. The ld that is called is determined by the @option{--with-ld}
10263 configure option, GCC's program search path, and finally by the user's
10264 @env{PATH}. The linker used by GCC can be printed using @samp{which
10265 `gcc -print-prog-name=ld`}. This option is only available on the 64 bit
10266 HP-UX GCC, i.e.@: configured with @samp{hppa*64*-*-hpux*}.
10269 @opindex mno-long-calls
10270 Generate code that uses long call sequences. This ensures that a call
10271 is always able to reach linker generated stubs. The default is to generate
10272 long calls only when the distance from the call site to the beginning
10273 of the function or translation unit, as the case may be, exceeds a
10274 predefined limit set by the branch type being used. The limits for
10275 normal calls are 7,600,000 and 240,000 bytes, respectively for the
10276 PA 2.0 and PA 1.X architectures. Sibcalls are always limited at
10279 Distances are measured from the beginning of functions when using the
10280 @option{-ffunction-sections} option, or when using the @option{-mgas}
10281 and @option{-mno-portable-runtime} options together under HP-UX with
10284 It is normally not desirable to use this option as it will degrade
10285 performance. However, it may be useful in large applications,
10286 particularly when partial linking is used to build the application.
10288 The types of long calls used depends on the capabilities of the
10289 assembler and linker, and the type of code being generated. The
10290 impact on systems that support long absolute calls, and long pic
10291 symbol-difference or pc-relative calls should be relatively small.
10292 However, an indirect call is used on 32-bit ELF systems in pic code
10293 and it is quite long.
10295 @item -munix=@var{unix-std}
10297 Generate compiler predefines and select a startfile for the specified
10298 UNIX standard. The choices for @var{unix-std} are @samp{93}, @samp{95}
10299 and @samp{98}. @samp{93} is supported on all HP-UX versions. @samp{95}
10300 is available on HP-UX 10.10 and later. @samp{98} is available on HP-UX
10301 11.11 and later. The default values are @samp{93} for HP-UX 10.00,
10302 @samp{95} for HP-UX 10.10 though to 11.00, and @samp{98} for HP-UX 11.11
10305 @option{-munix=93} provides the same predefines as GCC 3.3 and 3.4.
10306 @option{-munix=95} provides additional predefines for @code{XOPEN_UNIX}
10307 and @code{_XOPEN_SOURCE_EXTENDED}, and the startfile @file{unix95.o}.
10308 @option{-munix=98} provides additional predefines for @code{_XOPEN_UNIX},
10309 @code{_XOPEN_SOURCE_EXTENDED}, @code{_INCLUDE__STDC_A1_SOURCE} and
10310 @code{_INCLUDE_XOPEN_SOURCE_500}, and the startfile @file{unix98.o}.
10312 It is @emph{important} to note that this option changes the interfaces
10313 for various library routines. It also affects the operational behavior
10314 of the C library. Thus, @emph{extreme} care is needed in using this
10317 Library code that is intended to operate with more than one UNIX
10318 standard must test, set and restore the variable @var{__xpg4_extended_mask}
10319 as appropriate. Most GNU software doesn't provide this capability.
10323 Suppress the generation of link options to search libdld.sl when the
10324 @option{-static} option is specified on HP-UX 10 and later.
10328 The HP-UX implementation of setlocale in libc has a dependency on
10329 libdld.sl. There isn't an archive version of libdld.sl. Thus,
10330 when the @option{-static} option is specified, special link options
10331 are needed to resolve this dependency.
10333 On HP-UX 10 and later, the GCC driver adds the necessary options to
10334 link with libdld.sl when the @option{-static} option is specified.
10335 This causes the resulting binary to be dynamic. On the 64-bit port,
10336 the linkers generate dynamic binaries by default in any case. The
10337 @option{-nolibdld} option can be used to prevent the GCC driver from
10338 adding these link options.
10342 Add support for multithreading with the @dfn{dce thread} library
10343 under HP-UX@. This option sets flags for both the preprocessor and
10347 @node i386 and x86-64 Options
10348 @subsection Intel 386 and AMD x86-64 Options
10349 @cindex i386 Options
10350 @cindex x86-64 Options
10351 @cindex Intel 386 Options
10352 @cindex AMD x86-64 Options
10354 These @samp{-m} options are defined for the i386 and x86-64 family of
10358 @item -mtune=@var{cpu-type}
10360 Tune to @var{cpu-type} everything applicable about the generated code, except
10361 for the ABI and the set of available instructions. The choices for
10362 @var{cpu-type} are:
10365 Produce code optimized for the most common IA32/AMD64/EM64T processors.
10366 If you know the CPU on which your code will run, then you should use
10367 the corresponding @option{-mtune} option instead of
10368 @option{-mtune=generic}. But, if you do not know exactly what CPU users
10369 of your application will have, then you should use this option.
10371 As new processors are deployed in the marketplace, the behavior of this
10372 option will change. Therefore, if you upgrade to a newer version of
10373 GCC, the code generated option will change to reflect the processors
10374 that were most common when that version of GCC was released.
10376 There is no @option{-march=generic} option because @option{-march}
10377 indicates the instruction set the compiler can use, and there is no
10378 generic instruction set applicable to all processors. In contrast,
10379 @option{-mtune} indicates the processor (or, in this case, collection of
10380 processors) for which the code is optimized.
10382 This selects the CPU to tune for at compilation time by determining
10383 the processor type of the compiling machine. Using @option{-mtune=native}
10384 will produce code optimized for the local machine under the constraints
10385 of the selected instruction set. Using @option{-march=native} will
10386 enable all instruction subsets supported by the local machine (hence
10387 the result might not run on different machines).
10389 Original Intel's i386 CPU@.
10391 Intel's i486 CPU@. (No scheduling is implemented for this chip.)
10392 @item i586, pentium
10393 Intel Pentium CPU with no MMX support.
10395 Intel PentiumMMX CPU based on Pentium core with MMX instruction set support.
10397 Intel PentiumPro CPU@.
10399 Same as @code{generic}, but when used as @code{march} option, PentiumPro
10400 instruction set will be used, so the code will run on all i686 family chips.
10402 Intel Pentium2 CPU based on PentiumPro core with MMX instruction set support.
10403 @item pentium3, pentium3m
10404 Intel Pentium3 CPU based on PentiumPro core with MMX and SSE instruction set
10407 Low power version of Intel Pentium3 CPU with MMX, SSE and SSE2 instruction set
10408 support. Used by Centrino notebooks.
10409 @item pentium4, pentium4m
10410 Intel Pentium4 CPU with MMX, SSE and SSE2 instruction set support.
10412 Improved version of Intel Pentium4 CPU with MMX, SSE, SSE2 and SSE3 instruction
10415 Improved version of Intel Pentium4 CPU with 64-bit extensions, MMX, SSE,
10416 SSE2 and SSE3 instruction set support.
10418 Intel Core2 CPU with 64-bit extensions, MMX, SSE, SSE2, SSE3 and SSSE3
10419 instruction set support.
10421 AMD K6 CPU with MMX instruction set support.
10423 Improved versions of AMD K6 CPU with MMX and 3dNOW!@: instruction set support.
10424 @item athlon, athlon-tbird
10425 AMD Athlon CPU with MMX, 3dNOW!, enhanced 3dNOW!@: and SSE prefetch instructions
10427 @item athlon-4, athlon-xp, athlon-mp
10428 Improved AMD Athlon CPU with MMX, 3dNOW!, enhanced 3dNOW!@: and full SSE
10429 instruction set support.
10430 @item k8, opteron, athlon64, athlon-fx
10431 AMD K8 core based CPUs with x86-64 instruction set support. (This supersets
10432 MMX, SSE, SSE2, 3dNOW!, enhanced 3dNOW!@: and 64-bit instruction set extensions.)
10433 @item k8-sse3, opteron-sse3, athlon64-sse3
10434 Improved versions of k8, opteron and athlon64 with SSE3 instruction set support.
10435 @item amdfam10, barcelona
10436 AMD Family 10h core based CPUs with x86-64 instruction set support. (This
10437 supersets MMX, SSE, SSE2, SSE3, SSE4A, 3dNOW!, enhanced 3dNOW!, ABM and 64-bit
10438 instruction set extensions.)
10440 IDT Winchip C6 CPU, dealt in same way as i486 with additional MMX instruction
10443 IDT Winchip2 CPU, dealt in same way as i486 with additional MMX and 3dNOW!@:
10444 instruction set support.
10446 Via C3 CPU with MMX and 3dNOW!@: instruction set support. (No scheduling is
10447 implemented for this chip.)
10449 Via C3-2 CPU with MMX and SSE instruction set support. (No scheduling is
10450 implemented for this chip.)
10452 Embedded AMD CPU with MMX and 3dNOW! instruction set support.
10455 While picking a specific @var{cpu-type} will schedule things appropriately
10456 for that particular chip, the compiler will not generate any code that
10457 does not run on the i386 without the @option{-march=@var{cpu-type}} option
10460 @item -march=@var{cpu-type}
10462 Generate instructions for the machine type @var{cpu-type}. The choices
10463 for @var{cpu-type} are the same as for @option{-mtune}. Moreover,
10464 specifying @option{-march=@var{cpu-type}} implies @option{-mtune=@var{cpu-type}}.
10466 @item -mcpu=@var{cpu-type}
10468 A deprecated synonym for @option{-mtune}.
10470 @item -mfpmath=@var{unit}
10472 Generate floating point arithmetics for selected unit @var{unit}. The choices
10473 for @var{unit} are:
10477 Use the standard 387 floating point coprocessor present majority of chips and
10478 emulated otherwise. Code compiled with this option will run almost everywhere.
10479 The temporary results are computed in 80bit precision instead of precision
10480 specified by the type resulting in slightly different results compared to most
10481 of other chips. See @option{-ffloat-store} for more detailed description.
10483 This is the default choice for i386 compiler.
10486 Use scalar floating point instructions present in the SSE instruction set.
10487 This instruction set is supported by Pentium3 and newer chips, in the AMD line
10488 by Athlon-4, Athlon-xp and Athlon-mp chips. The earlier version of SSE
10489 instruction set supports only single precision arithmetics, thus the double and
10490 extended precision arithmetics is still done using 387. Later version, present
10491 only in Pentium4 and the future AMD x86-64 chips supports double precision
10494 For the i386 compiler, you need to use @option{-march=@var{cpu-type}}, @option{-msse}
10495 or @option{-msse2} switches to enable SSE extensions and make this option
10496 effective. For the x86-64 compiler, these extensions are enabled by default.
10498 The resulting code should be considerably faster in the majority of cases and avoid
10499 the numerical instability problems of 387 code, but may break some existing
10500 code that expects temporaries to be 80bit.
10502 This is the default choice for the x86-64 compiler.
10505 Attempt to utilize both instruction sets at once. This effectively double the
10506 amount of available registers and on chips with separate execution units for
10507 387 and SSE the execution resources too. Use this option with care, as it is
10508 still experimental, because the GCC register allocator does not model separate
10509 functional units well resulting in instable performance.
10512 @item -masm=@var{dialect}
10513 @opindex masm=@var{dialect}
10514 Output asm instructions using selected @var{dialect}. Supported
10515 choices are @samp{intel} or @samp{att} (the default one). Darwin does
10516 not support @samp{intel}.
10519 @itemx -mno-ieee-fp
10521 @opindex mno-ieee-fp
10522 Control whether or not the compiler uses IEEE floating point
10523 comparisons. These handle correctly the case where the result of a
10524 comparison is unordered.
10527 @opindex msoft-float
10528 Generate output containing library calls for floating point.
10529 @strong{Warning:} the requisite libraries are not part of GCC@.
10530 Normally the facilities of the machine's usual C compiler are used, but
10531 this can't be done directly in cross-compilation. You must make your
10532 own arrangements to provide suitable library functions for
10535 On machines where a function returns floating point results in the 80387
10536 register stack, some floating point opcodes may be emitted even if
10537 @option{-msoft-float} is used.
10539 @item -mno-fp-ret-in-387
10540 @opindex mno-fp-ret-in-387
10541 Do not use the FPU registers for return values of functions.
10543 The usual calling convention has functions return values of types
10544 @code{float} and @code{double} in an FPU register, even if there
10545 is no FPU@. The idea is that the operating system should emulate
10548 The option @option{-mno-fp-ret-in-387} causes such values to be returned
10549 in ordinary CPU registers instead.
10551 @item -mno-fancy-math-387
10552 @opindex mno-fancy-math-387
10553 Some 387 emulators do not support the @code{sin}, @code{cos} and
10554 @code{sqrt} instructions for the 387. Specify this option to avoid
10555 generating those instructions. This option is the default on FreeBSD,
10556 OpenBSD and NetBSD@. This option is overridden when @option{-march}
10557 indicates that the target cpu will always have an FPU and so the
10558 instruction will not need emulation. As of revision 2.6.1, these
10559 instructions are not generated unless you also use the
10560 @option{-funsafe-math-optimizations} switch.
10562 @item -malign-double
10563 @itemx -mno-align-double
10564 @opindex malign-double
10565 @opindex mno-align-double
10566 Control whether GCC aligns @code{double}, @code{long double}, and
10567 @code{long long} variables on a two word boundary or a one word
10568 boundary. Aligning @code{double} variables on a two word boundary will
10569 produce code that runs somewhat faster on a @samp{Pentium} at the
10570 expense of more memory.
10572 On x86-64, @option{-malign-double} is enabled by default.
10574 @strong{Warning:} if you use the @option{-malign-double} switch,
10575 structures containing the above types will be aligned differently than
10576 the published application binary interface specifications for the 386
10577 and will not be binary compatible with structures in code compiled
10578 without that switch.
10580 @item -m96bit-long-double
10581 @itemx -m128bit-long-double
10582 @opindex m96bit-long-double
10583 @opindex m128bit-long-double
10584 These switches control the size of @code{long double} type. The i386
10585 application binary interface specifies the size to be 96 bits,
10586 so @option{-m96bit-long-double} is the default in 32 bit mode.
10588 Modern architectures (Pentium and newer) would prefer @code{long double}
10589 to be aligned to an 8 or 16 byte boundary. In arrays or structures
10590 conforming to the ABI, this would not be possible. So specifying a
10591 @option{-m128bit-long-double} will align @code{long double}
10592 to a 16 byte boundary by padding the @code{long double} with an additional
10595 In the x86-64 compiler, @option{-m128bit-long-double} is the default choice as
10596 its ABI specifies that @code{long double} is to be aligned on 16 byte boundary.
10598 Notice that neither of these options enable any extra precision over the x87
10599 standard of 80 bits for a @code{long double}.
10601 @strong{Warning:} if you override the default value for your target ABI, the
10602 structures and arrays containing @code{long double} variables will change
10603 their size as well as function calling convention for function taking
10604 @code{long double} will be modified. Hence they will not be binary
10605 compatible with arrays or structures in code compiled without that switch.
10607 @item -mmlarge-data-threshold=@var{number}
10608 @opindex mlarge-data-threshold=@var{number}
10609 When @option{-mcmodel=medium} is specified, the data greater than
10610 @var{threshold} are placed in large data section. This value must be the
10611 same across all object linked into the binary and defaults to 65535.
10615 Use a different function-calling convention, in which functions that
10616 take a fixed number of arguments return with the @code{ret} @var{num}
10617 instruction, which pops their arguments while returning. This saves one
10618 instruction in the caller since there is no need to pop the arguments
10621 You can specify that an individual function is called with this calling
10622 sequence with the function attribute @samp{stdcall}. You can also
10623 override the @option{-mrtd} option by using the function attribute
10624 @samp{cdecl}. @xref{Function Attributes}.
10626 @strong{Warning:} this calling convention is incompatible with the one
10627 normally used on Unix, so you cannot use it if you need to call
10628 libraries compiled with the Unix compiler.
10630 Also, you must provide function prototypes for all functions that
10631 take variable numbers of arguments (including @code{printf});
10632 otherwise incorrect code will be generated for calls to those
10635 In addition, seriously incorrect code will result if you call a
10636 function with too many arguments. (Normally, extra arguments are
10637 harmlessly ignored.)
10639 @item -mregparm=@var{num}
10641 Control how many registers are used to pass integer arguments. By
10642 default, no registers are used to pass arguments, and at most 3
10643 registers can be used. You can control this behavior for a specific
10644 function by using the function attribute @samp{regparm}.
10645 @xref{Function Attributes}.
10647 @strong{Warning:} if you use this switch, and
10648 @var{num} is nonzero, then you must build all modules with the same
10649 value, including any libraries. This includes the system libraries and
10653 @opindex msseregparm
10654 Use SSE register passing conventions for float and double arguments
10655 and return values. You can control this behavior for a specific
10656 function by using the function attribute @samp{sseregparm}.
10657 @xref{Function Attributes}.
10659 @strong{Warning:} if you use this switch then you must build all
10660 modules with the same value, including any libraries. This includes
10661 the system libraries and startup modules.
10670 Set 80387 floating-point precision to 32, 64 or 80 bits. When @option{-mpc32}
10671 is specified, the significands of results of floating-point operations are
10672 rounded to 24 bits (single precision); @option{-mpc64} rounds the the
10673 significands of results of floating-point operations to 53 bits (double
10674 precision) and @option{-mpc80} rounds the significands of results of
10675 floating-point operations to 64 bits (extended double precision), which is
10676 the default. When this option is used, floating-point operations in higher
10677 precisions are not available to the programmer without setting the FPU
10678 control word explicitly.
10680 Setting the rounding of floating-point operations to less than the default
10681 80 bits can speed some programs by 2% or more. Note that some mathematical
10682 libraries assume that extended precision (80 bit) floating-point operations
10683 are enabled by default; routines in such libraries could suffer significant
10684 loss of accuracy, typically through so-called "catastrophic cancellation",
10685 when this option is used to set the precision to less than extended precision.
10687 @item -mstackrealign
10688 @opindex mstackrealign
10689 Realign the stack at entry. On the Intel x86, the
10690 @option{-mstackrealign} option will generate an alternate prologue and
10691 epilogue that realigns the runtime stack. This supports mixing legacy
10692 codes that keep a 4-byte aligned stack with modern codes that keep a
10693 16-byte stack for SSE compatibility. The alternate prologue and
10694 epilogue are slower and bigger than the regular ones, and the
10695 alternate prologue requires an extra scratch register; this lowers the
10696 number of registers available if used in conjunction with the
10697 @code{regparm} attribute. The @option{-mstackrealign} option is
10698 incompatible with the nested function prologue; this is considered a
10699 hard error. See also the attribute @code{force_align_arg_pointer},
10700 applicable to individual functions.
10702 @item -mpreferred-stack-boundary=@var{num}
10703 @opindex mpreferred-stack-boundary
10704 Attempt to keep the stack boundary aligned to a 2 raised to @var{num}
10705 byte boundary. If @option{-mpreferred-stack-boundary} is not specified,
10706 the default is 4 (16 bytes or 128 bits).
10708 On Pentium and PentiumPro, @code{double} and @code{long double} values
10709 should be aligned to an 8 byte boundary (see @option{-malign-double}) or
10710 suffer significant run time performance penalties. On Pentium III, the
10711 Streaming SIMD Extension (SSE) data type @code{__m128} may not work
10712 properly if it is not 16 byte aligned.
10714 To ensure proper alignment of this values on the stack, the stack boundary
10715 must be as aligned as that required by any value stored on the stack.
10716 Further, every function must be generated such that it keeps the stack
10717 aligned. Thus calling a function compiled with a higher preferred
10718 stack boundary from a function compiled with a lower preferred stack
10719 boundary will most likely misalign the stack. It is recommended that
10720 libraries that use callbacks always use the default setting.
10722 This extra alignment does consume extra stack space, and generally
10723 increases code size. Code that is sensitive to stack space usage, such
10724 as embedded systems and operating system kernels, may want to reduce the
10725 preferred alignment to @option{-mpreferred-stack-boundary=2}.
10759 These switches enable or disable the use of instructions in the MMX,
10760 SSE, SSE2, SSE3, SSSE3, SSE4.1, SSE4A, SSE5, ABM or 3DNow!@: extended
10762 These extensions are also available as built-in functions: see
10763 @ref{X86 Built-in Functions}, for details of the functions enabled and
10764 disabled by these switches.
10766 To have SSE/SSE2 instructions generated automatically from floating-point
10767 code (as opposed to 387 instructions), see @option{-mfpmath=sse}.
10769 These options will enable GCC to use these extended instructions in
10770 generated code, even without @option{-mfpmath=sse}. Applications which
10771 perform runtime CPU detection must compile separate files for each
10772 supported architecture, using the appropriate flags. In particular,
10773 the file containing the CPU detection code should be compiled without
10778 This option will enable GCC to use CMPXCHG16B instruction in generated code.
10779 CMPXCHG16B allows for atomic operations on 128-bit double quadword (or oword)
10780 data types. This is useful for high resolution counters that could be updated
10781 by multiple processors (or cores). This instruction is generated as part of
10782 atomic built-in functions: see @ref{Atomic Builtins} for details.
10786 This option will enable GCC to use SAHF instruction in generated 64-bit code.
10787 Early Intel CPUs with Intel 64 lacked LAHF and SAHF instructions supported
10788 by AMD64 until introduction of Pentium 4 G1 step in December 2005. LAHF and
10789 SAHF are load and store instructions, respectively, for certain status flags.
10790 In 64-bit mode, SAHF instruction is used to optimize @code{fmod}, @code{drem}
10791 or @code{remainder} built-in functions: see @ref{Other Builtins} for details.
10795 This option will enable GCC to use RCPSS and RSQRTSS instructions (and their
10796 vectorized variants RCPPS and RSQRTPS) with an additional Newton-Rhapson step
10797 to increase precision instead of DIVSS and SQRTSS (and their vectorized
10798 variants) for single precision floating point arguments. These instructions
10799 are generated only when @option{-funsafe-math-optimizations} is enabled
10800 together with @option{-finite-math-only} and @option{-fno-trapping-math}.
10801 Note that while the throughput of the sequence is higher than the throughput
10802 of the non-reciprocal instruction, the precision of the sequence can be
10803 decreased by up to 2 ulp (i.e. the inverse of 1.0 equals 0.99999994).
10805 @item -mveclibabi=@var{type}
10806 @opindex mveclibabi
10807 Specifies the ABI type to use for vectorizing intrinsics using an
10808 external library. Supported types are @code{acml} for the AMD
10809 math core library style of interfacing. GCC will currently emit
10810 calls to @code{__vrd2_sin}, @code{__vrd2_cos}, @code{__vrd2_exp},
10811 @code{__vrd2_log}, @code{__vrd2_log2}, @code{__vrd2_log10},
10812 @code{__vrs4_sinf}, @code{__vrs4_cosf}, @code{__vrs4_expf},
10813 @code{__vrs4_logf}, @code{__vrs4_log2f}, @code{__vrs4_log10f}
10814 and @code{__vrs4_powf} when using this type and @option{-ftree-vectorize}
10815 is enabled. A ACML ABI compatible library will have to be specified
10819 @itemx -mno-push-args
10820 @opindex mpush-args
10821 @opindex mno-push-args
10822 Use PUSH operations to store outgoing parameters. This method is shorter
10823 and usually equally fast as method using SUB/MOV operations and is enabled
10824 by default. In some cases disabling it may improve performance because of
10825 improved scheduling and reduced dependencies.
10827 @item -maccumulate-outgoing-args
10828 @opindex maccumulate-outgoing-args
10829 If enabled, the maximum amount of space required for outgoing arguments will be
10830 computed in the function prologue. This is faster on most modern CPUs
10831 because of reduced dependencies, improved scheduling and reduced stack usage
10832 when preferred stack boundary is not equal to 2. The drawback is a notable
10833 increase in code size. This switch implies @option{-mno-push-args}.
10837 Support thread-safe exception handling on @samp{Mingw32}. Code that relies
10838 on thread-safe exception handling must compile and link all code with the
10839 @option{-mthreads} option. When compiling, @option{-mthreads} defines
10840 @option{-D_MT}; when linking, it links in a special thread helper library
10841 @option{-lmingwthrd} which cleans up per thread exception handling data.
10843 @item -mno-align-stringops
10844 @opindex mno-align-stringops
10845 Do not align destination of inlined string operations. This switch reduces
10846 code size and improves performance in case the destination is already aligned,
10847 but GCC doesn't know about it.
10849 @item -minline-all-stringops
10850 @opindex minline-all-stringops
10851 By default GCC inlines string operations only when destination is known to be
10852 aligned at least to 4 byte boundary. This enables more inlining, increase code
10853 size, but may improve performance of code that depends on fast memcpy, strlen
10854 and memset for short lengths.
10856 @item -minline-stringops-dynamically
10857 @opindex minline-stringops-dynamically
10858 For string operation of unknown size, inline runtime checks so for small
10859 blocks inline code is used, while for large blocks library call is used.
10861 @item -mstringop-strategy=@var{alg}
10862 @opindex mstringop-strategy=@var{alg}
10863 Overwrite internal decision heuristic about particular algorithm to inline
10864 string operation with. The allowed values are @code{rep_byte},
10865 @code{rep_4byte}, @code{rep_8byte} for expanding using i386 @code{rep} prefix
10866 of specified size, @code{byte_loop}, @code{loop}, @code{unrolled_loop} for
10867 expanding inline loop, @code{libcall} for always expanding library call.
10869 @item -momit-leaf-frame-pointer
10870 @opindex momit-leaf-frame-pointer
10871 Don't keep the frame pointer in a register for leaf functions. This
10872 avoids the instructions to save, set up and restore frame pointers and
10873 makes an extra register available in leaf functions. The option
10874 @option{-fomit-frame-pointer} removes the frame pointer for all functions
10875 which might make debugging harder.
10877 @item -mtls-direct-seg-refs
10878 @itemx -mno-tls-direct-seg-refs
10879 @opindex mtls-direct-seg-refs
10880 Controls whether TLS variables may be accessed with offsets from the
10881 TLS segment register (@code{%gs} for 32-bit, @code{%fs} for 64-bit),
10882 or whether the thread base pointer must be added. Whether or not this
10883 is legal depends on the operating system, and whether it maps the
10884 segment to cover the entire TLS area.
10886 For systems that use GNU libc, the default is on.
10889 @itemx -mno-fused-madd
10890 @opindex mfused-madd
10891 Enable automatic generation of fused floating point multiply-add instructions
10892 if the ISA supports such instructions. The -mfused-madd option is on by
10893 default. The fused multiply-add instructions have a different
10894 rounding behavior compared to executing a multiply followed by an add.
10897 These @samp{-m} switches are supported in addition to the above
10898 on AMD x86-64 processors in 64-bit environments.
10905 Generate code for a 32-bit or 64-bit environment.
10906 The 32-bit environment sets int, long and pointer to 32 bits and
10907 generates code that runs on any i386 system.
10908 The 64-bit environment sets int to 32 bits and long and pointer
10909 to 64 bits and generates code for AMD's x86-64 architecture. For
10910 darwin only the -m64 option turns off the @option{-fno-pic} and
10911 @option{-mdynamic-no-pic} options.
10913 @item -mno-red-zone
10914 @opindex no-red-zone
10915 Do not use a so called red zone for x86-64 code. The red zone is mandated
10916 by the x86-64 ABI, it is a 128-byte area beyond the location of the
10917 stack pointer that will not be modified by signal or interrupt handlers
10918 and therefore can be used for temporary data without adjusting the stack
10919 pointer. The flag @option{-mno-red-zone} disables this red zone.
10921 @item -mcmodel=small
10922 @opindex mcmodel=small
10923 Generate code for the small code model: the program and its symbols must
10924 be linked in the lower 2 GB of the address space. Pointers are 64 bits.
10925 Programs can be statically or dynamically linked. This is the default
10928 @item -mcmodel=kernel
10929 @opindex mcmodel=kernel
10930 Generate code for the kernel code model. The kernel runs in the
10931 negative 2 GB of the address space.
10932 This model has to be used for Linux kernel code.
10934 @item -mcmodel=medium
10935 @opindex mcmodel=medium
10936 Generate code for the medium model: The program is linked in the lower 2
10937 GB of the address space but symbols can be located anywhere in the
10938 address space. Programs can be statically or dynamically linked, but
10939 building of shared libraries are not supported with the medium model.
10941 @item -mcmodel=large
10942 @opindex mcmodel=large
10943 Generate code for the large model: This model makes no assumptions
10944 about addresses and sizes of sections.
10947 @node IA-64 Options
10948 @subsection IA-64 Options
10949 @cindex IA-64 Options
10951 These are the @samp{-m} options defined for the Intel IA-64 architecture.
10955 @opindex mbig-endian
10956 Generate code for a big endian target. This is the default for HP-UX@.
10958 @item -mlittle-endian
10959 @opindex mlittle-endian
10960 Generate code for a little endian target. This is the default for AIX5
10966 @opindex mno-gnu-as
10967 Generate (or don't) code for the GNU assembler. This is the default.
10968 @c Also, this is the default if the configure option @option{--with-gnu-as}
10974 @opindex mno-gnu-ld
10975 Generate (or don't) code for the GNU linker. This is the default.
10976 @c Also, this is the default if the configure option @option{--with-gnu-ld}
10981 Generate code that does not use a global pointer register. The result
10982 is not position independent code, and violates the IA-64 ABI@.
10984 @item -mvolatile-asm-stop
10985 @itemx -mno-volatile-asm-stop
10986 @opindex mvolatile-asm-stop
10987 @opindex mno-volatile-asm-stop
10988 Generate (or don't) a stop bit immediately before and after volatile asm
10991 @item -mregister-names
10992 @itemx -mno-register-names
10993 @opindex mregister-names
10994 @opindex mno-register-names
10995 Generate (or don't) @samp{in}, @samp{loc}, and @samp{out} register names for
10996 the stacked registers. This may make assembler output more readable.
11002 Disable (or enable) optimizations that use the small data section. This may
11003 be useful for working around optimizer bugs.
11005 @item -mconstant-gp
11006 @opindex mconstant-gp
11007 Generate code that uses a single constant global pointer value. This is
11008 useful when compiling kernel code.
11012 Generate code that is self-relocatable. This implies @option{-mconstant-gp}.
11013 This is useful when compiling firmware code.
11015 @item -minline-float-divide-min-latency
11016 @opindex minline-float-divide-min-latency
11017 Generate code for inline divides of floating point values
11018 using the minimum latency algorithm.
11020 @item -minline-float-divide-max-throughput
11021 @opindex minline-float-divide-max-throughput
11022 Generate code for inline divides of floating point values
11023 using the maximum throughput algorithm.
11025 @item -minline-int-divide-min-latency
11026 @opindex minline-int-divide-min-latency
11027 Generate code for inline divides of integer values
11028 using the minimum latency algorithm.
11030 @item -minline-int-divide-max-throughput
11031 @opindex minline-int-divide-max-throughput
11032 Generate code for inline divides of integer values
11033 using the maximum throughput algorithm.
11035 @item -minline-sqrt-min-latency
11036 @opindex minline-sqrt-min-latency
11037 Generate code for inline square roots
11038 using the minimum latency algorithm.
11040 @item -minline-sqrt-max-throughput
11041 @opindex minline-sqrt-max-throughput
11042 Generate code for inline square roots
11043 using the maximum throughput algorithm.
11045 @item -mno-dwarf2-asm
11046 @itemx -mdwarf2-asm
11047 @opindex mno-dwarf2-asm
11048 @opindex mdwarf2-asm
11049 Don't (or do) generate assembler code for the DWARF2 line number debugging
11050 info. This may be useful when not using the GNU assembler.
11052 @item -mearly-stop-bits
11053 @itemx -mno-early-stop-bits
11054 @opindex mearly-stop-bits
11055 @opindex mno-early-stop-bits
11056 Allow stop bits to be placed earlier than immediately preceding the
11057 instruction that triggered the stop bit. This can improve instruction
11058 scheduling, but does not always do so.
11060 @item -mfixed-range=@var{register-range}
11061 @opindex mfixed-range
11062 Generate code treating the given register range as fixed registers.
11063 A fixed register is one that the register allocator can not use. This is
11064 useful when compiling kernel code. A register range is specified as
11065 two registers separated by a dash. Multiple register ranges can be
11066 specified separated by a comma.
11068 @item -mtls-size=@var{tls-size}
11070 Specify bit size of immediate TLS offsets. Valid values are 14, 22, and
11073 @item -mtune=@var{cpu-type}
11075 Tune the instruction scheduling for a particular CPU, Valid values are
11076 itanium, itanium1, merced, itanium2, and mckinley.
11082 Add support for multithreading using the POSIX threads library. This
11083 option sets flags for both the preprocessor and linker. It does
11084 not affect the thread safety of object code produced by the compiler or
11085 that of libraries supplied with it. These are HP-UX specific flags.
11091 Generate code for a 32-bit or 64-bit environment.
11092 The 32-bit environment sets int, long and pointer to 32 bits.
11093 The 64-bit environment sets int to 32 bits and long and pointer
11094 to 64 bits. These are HP-UX specific flags.
11096 @item -mno-sched-br-data-spec
11097 @itemx -msched-br-data-spec
11098 @opindex mno-sched-br-data-spec
11099 @opindex msched-br-data-spec
11100 (Dis/En)able data speculative scheduling before reload.
11101 This will result in generation of the ld.a instructions and
11102 the corresponding check instructions (ld.c / chk.a).
11103 The default is 'disable'.
11105 @item -msched-ar-data-spec
11106 @itemx -mno-sched-ar-data-spec
11107 @opindex msched-ar-data-spec
11108 @opindex mno-sched-ar-data-spec
11109 (En/Dis)able data speculative scheduling after reload.
11110 This will result in generation of the ld.a instructions and
11111 the corresponding check instructions (ld.c / chk.a).
11112 The default is 'enable'.
11114 @item -mno-sched-control-spec
11115 @itemx -msched-control-spec
11116 @opindex mno-sched-control-spec
11117 @opindex msched-control-spec
11118 (Dis/En)able control speculative scheduling. This feature is
11119 available only during region scheduling (i.e.@: before reload).
11120 This will result in generation of the ld.s instructions and
11121 the corresponding check instructions chk.s .
11122 The default is 'disable'.
11124 @item -msched-br-in-data-spec
11125 @itemx -mno-sched-br-in-data-spec
11126 @opindex msched-br-in-data-spec
11127 @opindex mno-sched-br-in-data-spec
11128 (En/Dis)able speculative scheduling of the instructions that
11129 are dependent on the data speculative loads before reload.
11130 This is effective only with @option{-msched-br-data-spec} enabled.
11131 The default is 'enable'.
11133 @item -msched-ar-in-data-spec
11134 @itemx -mno-sched-ar-in-data-spec
11135 @opindex msched-ar-in-data-spec
11136 @opindex mno-sched-ar-in-data-spec
11137 (En/Dis)able speculative scheduling of the instructions that
11138 are dependent on the data speculative loads after reload.
11139 This is effective only with @option{-msched-ar-data-spec} enabled.
11140 The default is 'enable'.
11142 @item -msched-in-control-spec
11143 @itemx -mno-sched-in-control-spec
11144 @opindex msched-in-control-spec
11145 @opindex mno-sched-in-control-spec
11146 (En/Dis)able speculative scheduling of the instructions that
11147 are dependent on the control speculative loads.
11148 This is effective only with @option{-msched-control-spec} enabled.
11149 The default is 'enable'.
11152 @itemx -mno-sched-ldc
11153 @opindex msched-ldc
11154 @opindex mno-sched-ldc
11155 (En/Dis)able use of simple data speculation checks ld.c .
11156 If disabled, only chk.a instructions will be emitted to check
11157 data speculative loads.
11158 The default is 'enable'.
11160 @item -mno-sched-control-ldc
11161 @itemx -msched-control-ldc
11162 @opindex mno-sched-control-ldc
11163 @opindex msched-control-ldc
11164 (Dis/En)able use of ld.c instructions to check control speculative loads.
11165 If enabled, in case of control speculative load with no speculatively
11166 scheduled dependent instructions this load will be emitted as ld.sa and
11167 ld.c will be used to check it.
11168 The default is 'disable'.
11170 @item -mno-sched-spec-verbose
11171 @itemx -msched-spec-verbose
11172 @opindex mno-sched-spec-verbose
11173 @opindex msched-spec-verbose
11174 (Dis/En)able printing of the information about speculative motions.
11176 @item -mno-sched-prefer-non-data-spec-insns
11177 @itemx -msched-prefer-non-data-spec-insns
11178 @opindex mno-sched-prefer-non-data-spec-insns
11179 @opindex msched-prefer-non-data-spec-insns
11180 If enabled, data speculative instructions will be chosen for schedule
11181 only if there are no other choices at the moment. This will make
11182 the use of the data speculation much more conservative.
11183 The default is 'disable'.
11185 @item -mno-sched-prefer-non-control-spec-insns
11186 @itemx -msched-prefer-non-control-spec-insns
11187 @opindex mno-sched-prefer-non-control-spec-insns
11188 @opindex msched-prefer-non-control-spec-insns
11189 If enabled, control speculative instructions will be chosen for schedule
11190 only if there are no other choices at the moment. This will make
11191 the use of the control speculation much more conservative.
11192 The default is 'disable'.
11194 @item -mno-sched-count-spec-in-critical-path
11195 @itemx -msched-count-spec-in-critical-path
11196 @opindex mno-sched-count-spec-in-critical-path
11197 @opindex msched-count-spec-in-critical-path
11198 If enabled, speculative dependencies will be considered during
11199 computation of the instructions priorities. This will make the use of the
11200 speculation a bit more conservative.
11201 The default is 'disable'.
11206 @subsection M32C Options
11207 @cindex M32C options
11210 @item -mcpu=@var{name}
11212 Select the CPU for which code is generated. @var{name} may be one of
11213 @samp{r8c} for the R8C/Tiny series, @samp{m16c} for the M16C (up to
11214 /60) series, @samp{m32cm} for the M16C/80 series, or @samp{m32c} for
11215 the M32C/80 series.
11219 Specifies that the program will be run on the simulator. This causes
11220 an alternate runtime library to be linked in which supports, for
11221 example, file I/O@. You must not use this option when generating
11222 programs that will run on real hardware; you must provide your own
11223 runtime library for whatever I/O functions are needed.
11225 @item -memregs=@var{number}
11227 Specifies the number of memory-based pseudo-registers GCC will use
11228 during code generation. These pseudo-registers will be used like real
11229 registers, so there is a tradeoff between GCC's ability to fit the
11230 code into available registers, and the performance penalty of using
11231 memory instead of registers. Note that all modules in a program must
11232 be compiled with the same value for this option. Because of that, you
11233 must not use this option with the default runtime libraries gcc
11238 @node M32R/D Options
11239 @subsection M32R/D Options
11240 @cindex M32R/D options
11242 These @option{-m} options are defined for Renesas M32R/D architectures:
11247 Generate code for the M32R/2@.
11251 Generate code for the M32R/X@.
11255 Generate code for the M32R@. This is the default.
11257 @item -mmodel=small
11258 @opindex mmodel=small
11259 Assume all objects live in the lower 16MB of memory (so that their addresses
11260 can be loaded with the @code{ld24} instruction), and assume all subroutines
11261 are reachable with the @code{bl} instruction.
11262 This is the default.
11264 The addressability of a particular object can be set with the
11265 @code{model} attribute.
11267 @item -mmodel=medium
11268 @opindex mmodel=medium
11269 Assume objects may be anywhere in the 32-bit address space (the compiler
11270 will generate @code{seth/add3} instructions to load their addresses), and
11271 assume all subroutines are reachable with the @code{bl} instruction.
11273 @item -mmodel=large
11274 @opindex mmodel=large
11275 Assume objects may be anywhere in the 32-bit address space (the compiler
11276 will generate @code{seth/add3} instructions to load their addresses), and
11277 assume subroutines may not be reachable with the @code{bl} instruction
11278 (the compiler will generate the much slower @code{seth/add3/jl}
11279 instruction sequence).
11282 @opindex msdata=none
11283 Disable use of the small data area. Variables will be put into
11284 one of @samp{.data}, @samp{bss}, or @samp{.rodata} (unless the
11285 @code{section} attribute has been specified).
11286 This is the default.
11288 The small data area consists of sections @samp{.sdata} and @samp{.sbss}.
11289 Objects may be explicitly put in the small data area with the
11290 @code{section} attribute using one of these sections.
11292 @item -msdata=sdata
11293 @opindex msdata=sdata
11294 Put small global and static data in the small data area, but do not
11295 generate special code to reference them.
11298 @opindex msdata=use
11299 Put small global and static data in the small data area, and generate
11300 special instructions to reference them.
11304 @cindex smaller data references
11305 Put global and static objects less than or equal to @var{num} bytes
11306 into the small data or bss sections instead of the normal data or bss
11307 sections. The default value of @var{num} is 8.
11308 The @option{-msdata} option must be set to one of @samp{sdata} or @samp{use}
11309 for this option to have any effect.
11311 All modules should be compiled with the same @option{-G @var{num}} value.
11312 Compiling with different values of @var{num} may or may not work; if it
11313 doesn't the linker will give an error message---incorrect code will not be
11318 Makes the M32R specific code in the compiler display some statistics
11319 that might help in debugging programs.
11321 @item -malign-loops
11322 @opindex malign-loops
11323 Align all loops to a 32-byte boundary.
11325 @item -mno-align-loops
11326 @opindex mno-align-loops
11327 Do not enforce a 32-byte alignment for loops. This is the default.
11329 @item -missue-rate=@var{number}
11330 @opindex missue-rate=@var{number}
11331 Issue @var{number} instructions per cycle. @var{number} can only be 1
11334 @item -mbranch-cost=@var{number}
11335 @opindex mbranch-cost=@var{number}
11336 @var{number} can only be 1 or 2. If it is 1 then branches will be
11337 preferred over conditional code, if it is 2, then the opposite will
11340 @item -mflush-trap=@var{number}
11341 @opindex mflush-trap=@var{number}
11342 Specifies the trap number to use to flush the cache. The default is
11343 12. Valid numbers are between 0 and 15 inclusive.
11345 @item -mno-flush-trap
11346 @opindex mno-flush-trap
11347 Specifies that the cache cannot be flushed by using a trap.
11349 @item -mflush-func=@var{name}
11350 @opindex mflush-func=@var{name}
11351 Specifies the name of the operating system function to call to flush
11352 the cache. The default is @emph{_flush_cache}, but a function call
11353 will only be used if a trap is not available.
11355 @item -mno-flush-func
11356 @opindex mno-flush-func
11357 Indicates that there is no OS function for flushing the cache.
11361 @node M680x0 Options
11362 @subsection M680x0 Options
11363 @cindex M680x0 options
11365 These are the @samp{-m} options defined for M680x0 and ColdFire processors.
11366 The default settings depend on which architecture was selected when
11367 the compiler was configured; the defaults for the most common choices
11371 @item -march=@var{arch}
11373 Generate code for a specific M680x0 or ColdFire instruction set
11374 architecture. Permissible values of @var{arch} for M680x0
11375 architectures are: @samp{68000}, @samp{68010}, @samp{68020},
11376 @samp{68030}, @samp{68040}, @samp{68060} and @samp{cpu32}. ColdFire
11377 architectures are selected according to Freescale's ISA classification
11378 and the permissible values are: @samp{isaa}, @samp{isaaplus},
11379 @samp{isab} and @samp{isac}.
11381 gcc defines a macro @samp{__mcf@var{arch}__} whenever it is generating
11382 code for a ColdFire target. The @var{arch} in this macro is one of the
11383 @option{-march} arguments given above.
11385 When used together, @option{-march} and @option{-mtune} select code
11386 that runs on a family of similar processors but that is optimized
11387 for a particular microarchitecture.
11389 @item -mcpu=@var{cpu}
11391 Generate code for a specific M680x0 or ColdFire processor.
11392 The M680x0 @var{cpu}s are: @samp{68000}, @samp{68010}, @samp{68020},
11393 @samp{68030}, @samp{68040}, @samp{68060}, @samp{68302}, @samp{68332}
11394 and @samp{cpu32}. The ColdFire @var{cpu}s are given by the table
11395 below, which also classifies the CPUs into families:
11397 @multitable @columnfractions 0.20 0.80
11398 @item @strong{Family} @tab @strong{@samp{-mcpu} arguments}
11399 @item @samp{51qe} @tab @samp{51qe}
11400 @item @samp{5206} @tab @samp{5202} @samp{5204} @samp{5206}
11401 @item @samp{5206e} @tab @samp{5206e}
11402 @item @samp{5208} @tab @samp{5207} @samp{5208}
11403 @item @samp{5211a} @tab @samp{5210a} @samp{5211a}
11404 @item @samp{5213} @tab @samp{5211} @samp{5212} @samp{5213}
11405 @item @samp{5216} @tab @samp{5214} @samp{5216}
11406 @item @samp{52235} @tab @samp{52230} @samp{52231} @samp{52232} @samp{52233} @samp{52234} @samp{52235}
11407 @item @samp{5225} @tab @samp{5224} @samp{5225}
11408 @item @samp{5235} @tab @samp{5232} @samp{5233} @samp{5234} @samp{5235} @samp{523x}
11409 @item @samp{5249} @tab @samp{5249}
11410 @item @samp{5250} @tab @samp{5250}
11411 @item @samp{5271} @tab @samp{5270} @samp{5271}
11412 @item @samp{5272} @tab @samp{5272}
11413 @item @samp{5275} @tab @samp{5274} @samp{5275}
11414 @item @samp{5282} @tab @samp{5280} @samp{5281} @samp{5282} @samp{528x}
11415 @item @samp{5307} @tab @samp{5307}
11416 @item @samp{5329} @tab @samp{5327} @samp{5328} @samp{5329} @samp{532x}
11417 @item @samp{5373} @tab @samp{5372} @samp{5373} @samp{537x}
11418 @item @samp{5407} @tab @samp{5407}
11419 @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}
11422 @option{-mcpu=@var{cpu}} overrides @option{-march=@var{arch}} if
11423 @var{arch} is compatible with @var{cpu}. Other combinations of
11424 @option{-mcpu} and @option{-march} are rejected.
11426 gcc defines the macro @samp{__mcf_cpu_@var{cpu}} when ColdFire target
11427 @var{cpu} is selected. It also defines @samp{__mcf_family_@var{family}},
11428 where the value of @var{family} is given by the table above.
11430 @item -mtune=@var{tune}
11432 Tune the code for a particular microarchitecture, within the
11433 constraints set by @option{-march} and @option{-mcpu}.
11434 The M680x0 microarchitectures are: @samp{68000}, @samp{68010},
11435 @samp{68020}, @samp{68030}, @samp{68040}, @samp{68060}
11436 and @samp{cpu32}. The ColdFire microarchitectures
11437 are: @samp{cfv1}, @samp{cfv2}, @samp{cfv3}, @samp{cfv4} and @samp{cfv4e}.
11439 You can also use @option{-mtune=68020-40} for code that needs
11440 to run relatively well on 68020, 68030 and 68040 targets.
11441 @option{-mtune=68020-60} is similar but includes 68060 targets
11442 as well. These two options select the same tuning decisions as
11443 @option{-m68020-40} and @option{-m68020-60} respectively.
11445 gcc defines the macros @samp{__mc@var{arch}} and @samp{__mc@var{arch}__}
11446 when tuning for 680x0 architecture @var{arch}. It also defines
11447 @samp{mc@var{arch}} unless either @option{-ansi} or a non-GNU @option{-std}
11448 option is used. If gcc is tuning for a range of architectures,
11449 as selected by @option{-mtune=68020-40} or @option{-mtune=68020-60},
11450 it defines the macros for every architecture in the range.
11452 gcc also defines the macro @samp{__m@var{uarch}__} when tuning for
11453 ColdFire microarchitecture @var{uarch}, where @var{uarch} is one
11454 of the arguments given above.
11460 Generate output for a 68000. This is the default
11461 when the compiler is configured for 68000-based systems.
11462 It is equivalent to @option{-march=68000}.
11464 Use this option for microcontrollers with a 68000 or EC000 core,
11465 including the 68008, 68302, 68306, 68307, 68322, 68328 and 68356.
11469 Generate output for a 68010. This is the default
11470 when the compiler is configured for 68010-based systems.
11471 It is equivalent to @option{-march=68010}.
11477 Generate output for a 68020. This is the default
11478 when the compiler is configured for 68020-based systems.
11479 It is equivalent to @option{-march=68020}.
11483 Generate output for a 68030. This is the default when the compiler is
11484 configured for 68030-based systems. It is equivalent to
11485 @option{-march=68030}.
11489 Generate output for a 68040. This is the default when the compiler is
11490 configured for 68040-based systems. It is equivalent to
11491 @option{-march=68040}.
11493 This option inhibits the use of 68881/68882 instructions that have to be
11494 emulated by software on the 68040. Use this option if your 68040 does not
11495 have code to emulate those instructions.
11499 Generate output for a 68060. This is the default when the compiler is
11500 configured for 68060-based systems. It is equivalent to
11501 @option{-march=68060}.
11503 This option inhibits the use of 68020 and 68881/68882 instructions that
11504 have to be emulated by software on the 68060. Use this option if your 68060
11505 does not have code to emulate those instructions.
11509 Generate output for a CPU32. This is the default
11510 when the compiler is configured for CPU32-based systems.
11511 It is equivalent to @option{-march=cpu32}.
11513 Use this option for microcontrollers with a
11514 CPU32 or CPU32+ core, including the 68330, 68331, 68332, 68333, 68334,
11515 68336, 68340, 68341, 68349 and 68360.
11519 Generate output for a 520X ColdFire CPU@. This is the default
11520 when the compiler is configured for 520X-based systems.
11521 It is equivalent to @option{-mcpu=5206}, and is now deprecated
11522 in favor of that option.
11524 Use this option for microcontroller with a 5200 core, including
11525 the MCF5202, MCF5203, MCF5204 and MCF5206.
11529 Generate output for a 5206e ColdFire CPU@. The option is now
11530 deprecated in favor of the equivalent @option{-mcpu=5206e}.
11534 Generate output for a member of the ColdFire 528X family.
11535 The option is now deprecated in favor of the equivalent
11536 @option{-mcpu=528x}.
11540 Generate output for a ColdFire 5307 CPU@. The option is now deprecated
11541 in favor of the equivalent @option{-mcpu=5307}.
11545 Generate output for a ColdFire 5407 CPU@. The option is now deprecated
11546 in favor of the equivalent @option{-mcpu=5407}.
11550 Generate output for a ColdFire V4e family CPU (e.g.@: 547x/548x).
11551 This includes use of hardware floating point instructions.
11552 The option is equivalent to @option{-mcpu=547x}, and is now
11553 deprecated in favor of that option.
11557 Generate output for a 68040, without using any of the new instructions.
11558 This results in code which can run relatively efficiently on either a
11559 68020/68881 or a 68030 or a 68040. The generated code does use the
11560 68881 instructions that are emulated on the 68040.
11562 The option is equivalent to @option{-march=68020} @option{-mtune=68020-40}.
11566 Generate output for a 68060, without using any of the new instructions.
11567 This results in code which can run relatively efficiently on either a
11568 68020/68881 or a 68030 or a 68040. The generated code does use the
11569 68881 instructions that are emulated on the 68060.
11571 The option is equivalent to @option{-march=68020} @option{-mtune=68020-60}.
11575 @opindex mhard-float
11577 Generate floating-point instructions. This is the default for 68020
11578 and above, and for ColdFire devices that have an FPU@. It defines the
11579 macro @samp{__HAVE_68881__} on M680x0 targets and @samp{__mcffpu__}
11580 on ColdFire targets.
11583 @opindex msoft-float
11584 Do not generate floating-point instructions; use library calls instead.
11585 This is the default for 68000, 68010, and 68832 targets. It is also
11586 the default for ColdFire devices that have no FPU.
11592 Generate (do not generate) ColdFire hardware divide and remainder
11593 instructions. If @option{-march} is used without @option{-mcpu},
11594 the default is ``on'' for ColdFire architectures and ``off'' for M680x0
11595 architectures. Otherwise, the default is taken from the target CPU
11596 (either the default CPU, or the one specified by @option{-mcpu}). For
11597 example, the default is ``off'' for @option{-mcpu=5206} and ``on'' for
11598 @option{-mcpu=5206e}.
11600 gcc defines the macro @samp{__mcfhwdiv__} when this option is enabled.
11604 Consider type @code{int} to be 16 bits wide, like @code{short int}.
11605 Additionally, parameters passed on the stack are also aligned to a
11606 16-bit boundary even on targets whose API mandates promotion to 32-bit.
11610 Do not consider type @code{int} to be 16 bits wide. This is the default.
11613 @itemx -mno-bitfield
11614 @opindex mnobitfield
11615 @opindex mno-bitfield
11616 Do not use the bit-field instructions. The @option{-m68000}, @option{-mcpu32}
11617 and @option{-m5200} options imply @w{@option{-mnobitfield}}.
11621 Do use the bit-field instructions. The @option{-m68020} option implies
11622 @option{-mbitfield}. This is the default if you use a configuration
11623 designed for a 68020.
11627 Use a different function-calling convention, in which functions
11628 that take a fixed number of arguments return with the @code{rtd}
11629 instruction, which pops their arguments while returning. This
11630 saves one instruction in the caller since there is no need to pop
11631 the arguments there.
11633 This calling convention is incompatible with the one normally
11634 used on Unix, so you cannot use it if you need to call libraries
11635 compiled with the Unix compiler.
11637 Also, you must provide function prototypes for all functions that
11638 take variable numbers of arguments (including @code{printf});
11639 otherwise incorrect code will be generated for calls to those
11642 In addition, seriously incorrect code will result if you call a
11643 function with too many arguments. (Normally, extra arguments are
11644 harmlessly ignored.)
11646 The @code{rtd} instruction is supported by the 68010, 68020, 68030,
11647 68040, 68060 and CPU32 processors, but not by the 68000 or 5200.
11651 Do not use the calling conventions selected by @option{-mrtd}.
11652 This is the default.
11655 @itemx -mno-align-int
11656 @opindex malign-int
11657 @opindex mno-align-int
11658 Control whether GCC aligns @code{int}, @code{long}, @code{long long},
11659 @code{float}, @code{double}, and @code{long double} variables on a 32-bit
11660 boundary (@option{-malign-int}) or a 16-bit boundary (@option{-mno-align-int}).
11661 Aligning variables on 32-bit boundaries produces code that runs somewhat
11662 faster on processors with 32-bit busses at the expense of more memory.
11664 @strong{Warning:} if you use the @option{-malign-int} switch, GCC will
11665 align structures containing the above types differently than
11666 most published application binary interface specifications for the m68k.
11670 Use the pc-relative addressing mode of the 68000 directly, instead of
11671 using a global offset table. At present, this option implies @option{-fpic},
11672 allowing at most a 16-bit offset for pc-relative addressing. @option{-fPIC} is
11673 not presently supported with @option{-mpcrel}, though this could be supported for
11674 68020 and higher processors.
11676 @item -mno-strict-align
11677 @itemx -mstrict-align
11678 @opindex mno-strict-align
11679 @opindex mstrict-align
11680 Do not (do) assume that unaligned memory references will be handled by
11684 Generate code that allows the data segment to be located in a different
11685 area of memory from the text segment. This allows for execute in place in
11686 an environment without virtual memory management. This option implies
11689 @item -mno-sep-data
11690 Generate code that assumes that the data segment follows the text segment.
11691 This is the default.
11693 @item -mid-shared-library
11694 Generate code that supports shared libraries via the library ID method.
11695 This allows for execute in place and shared libraries in an environment
11696 without virtual memory management. This option implies @option{-fPIC}.
11698 @item -mno-id-shared-library
11699 Generate code that doesn't assume ID based shared libraries are being used.
11700 This is the default.
11702 @item -mshared-library-id=n
11703 Specified the identification number of the ID based shared library being
11704 compiled. Specifying a value of 0 will generate more compact code, specifying
11705 other values will force the allocation of that number to the current
11706 library but is no more space or time efficient than omitting this option.
11710 @node M68hc1x Options
11711 @subsection M68hc1x Options
11712 @cindex M68hc1x options
11714 These are the @samp{-m} options defined for the 68hc11 and 68hc12
11715 microcontrollers. The default values for these options depends on
11716 which style of microcontroller was selected when the compiler was configured;
11717 the defaults for the most common choices are given below.
11724 Generate output for a 68HC11. This is the default
11725 when the compiler is configured for 68HC11-based systems.
11731 Generate output for a 68HC12. This is the default
11732 when the compiler is configured for 68HC12-based systems.
11738 Generate output for a 68HCS12.
11740 @item -mauto-incdec
11741 @opindex mauto-incdec
11742 Enable the use of 68HC12 pre and post auto-increment and auto-decrement
11749 Enable the use of 68HC12 min and max instructions.
11752 @itemx -mno-long-calls
11753 @opindex mlong-calls
11754 @opindex mno-long-calls
11755 Treat all calls as being far away (near). If calls are assumed to be
11756 far away, the compiler will use the @code{call} instruction to
11757 call a function and the @code{rtc} instruction for returning.
11761 Consider type @code{int} to be 16 bits wide, like @code{short int}.
11763 @item -msoft-reg-count=@var{count}
11764 @opindex msoft-reg-count
11765 Specify the number of pseudo-soft registers which are used for the
11766 code generation. The maximum number is 32. Using more pseudo-soft
11767 register may or may not result in better code depending on the program.
11768 The default is 4 for 68HC11 and 2 for 68HC12.
11772 @node MCore Options
11773 @subsection MCore Options
11774 @cindex MCore options
11776 These are the @samp{-m} options defined for the Motorola M*Core
11782 @itemx -mno-hardlit
11784 @opindex mno-hardlit
11785 Inline constants into the code stream if it can be done in two
11786 instructions or less.
11792 Use the divide instruction. (Enabled by default).
11794 @item -mrelax-immediate
11795 @itemx -mno-relax-immediate
11796 @opindex mrelax-immediate
11797 @opindex mno-relax-immediate
11798 Allow arbitrary sized immediates in bit operations.
11800 @item -mwide-bitfields
11801 @itemx -mno-wide-bitfields
11802 @opindex mwide-bitfields
11803 @opindex mno-wide-bitfields
11804 Always treat bit-fields as int-sized.
11806 @item -m4byte-functions
11807 @itemx -mno-4byte-functions
11808 @opindex m4byte-functions
11809 @opindex mno-4byte-functions
11810 Force all functions to be aligned to a four byte boundary.
11812 @item -mcallgraph-data
11813 @itemx -mno-callgraph-data
11814 @opindex mcallgraph-data
11815 @opindex mno-callgraph-data
11816 Emit callgraph information.
11819 @itemx -mno-slow-bytes
11820 @opindex mslow-bytes
11821 @opindex mno-slow-bytes
11822 Prefer word access when reading byte quantities.
11824 @item -mlittle-endian
11825 @itemx -mbig-endian
11826 @opindex mlittle-endian
11827 @opindex mbig-endian
11828 Generate code for a little endian target.
11834 Generate code for the 210 processor.
11838 @subsection MIPS Options
11839 @cindex MIPS options
11845 Generate big-endian code.
11849 Generate little-endian code. This is the default for @samp{mips*el-*-*}
11852 @item -march=@var{arch}
11854 Generate code that will run on @var{arch}, which can be the name of a
11855 generic MIPS ISA, or the name of a particular processor.
11857 @samp{mips1}, @samp{mips2}, @samp{mips3}, @samp{mips4},
11858 @samp{mips32}, @samp{mips32r2}, and @samp{mips64}.
11859 The processor names are:
11860 @samp{4kc}, @samp{4km}, @samp{4kp}, @samp{4ksc},
11861 @samp{4kec}, @samp{4kem}, @samp{4kep}, @samp{4ksd},
11862 @samp{5kc}, @samp{5kf},
11864 @samp{24kc}, @samp{24kf2_1}, @samp{24kf1_1},
11865 @samp{24kec}, @samp{24kef2_1}, @samp{24kef1_1},
11866 @samp{34kc}, @samp{34kf2_1}, @samp{34kf1_1},
11867 @samp{74kc}, @samp{74kf2_1}, @samp{74kf1_1}, @samp{74kf3_2},
11870 @samp{r2000}, @samp{r3000}, @samp{r3900}, @samp{r4000}, @samp{r4400},
11871 @samp{r4600}, @samp{r4650}, @samp{r6000}, @samp{r8000},
11872 @samp{rm7000}, @samp{rm9000},
11875 @samp{vr4100}, @samp{vr4111}, @samp{vr4120}, @samp{vr4130}, @samp{vr4300},
11876 @samp{vr5000}, @samp{vr5400} and @samp{vr5500}.
11877 The special value @samp{from-abi} selects the
11878 most compatible architecture for the selected ABI (that is,
11879 @samp{mips1} for 32-bit ABIs and @samp{mips3} for 64-bit ABIs)@.
11881 In processor names, a final @samp{000} can be abbreviated as @samp{k}
11882 (for example, @samp{-march=r2k}). Prefixes are optional, and
11883 @samp{vr} may be written @samp{r}.
11885 Names of the form @samp{@var{n}f2_1} refer to processors with
11886 FPUs clocked at half the rate of the core, names of the form
11887 @samp{@var{n}f1_1} refer to processors with FPUs clocked at the same
11888 rate as the core, and names of the form @samp{@var{n}f3_2} refer to
11889 processors with FPUs clocked a ratio of 3:2 with respect to the core.
11890 For compatibility reasons, @samp{@var{n}f} is accepted as a synonym
11891 for @samp{@var{n}f2_1} while @samp{@var{n}x} and @samp{@var{b}fx} are
11892 accepted as synonyms for @samp{@var{n}f1_1}.
11894 GCC defines two macros based on the value of this option. The first
11895 is @samp{_MIPS_ARCH}, which gives the name of target architecture, as
11896 a string. The second has the form @samp{_MIPS_ARCH_@var{foo}},
11897 where @var{foo} is the capitalized value of @samp{_MIPS_ARCH}@.
11898 For example, @samp{-march=r2000} will set @samp{_MIPS_ARCH}
11899 to @samp{"r2000"} and define the macro @samp{_MIPS_ARCH_R2000}.
11901 Note that the @samp{_MIPS_ARCH} macro uses the processor names given
11902 above. In other words, it will have the full prefix and will not
11903 abbreviate @samp{000} as @samp{k}. In the case of @samp{from-abi},
11904 the macro names the resolved architecture (either @samp{"mips1"} or
11905 @samp{"mips3"}). It names the default architecture when no
11906 @option{-march} option is given.
11908 @item -mtune=@var{arch}
11910 Optimize for @var{arch}. Among other things, this option controls
11911 the way instructions are scheduled, and the perceived cost of arithmetic
11912 operations. The list of @var{arch} values is the same as for
11915 When this option is not used, GCC will optimize for the processor
11916 specified by @option{-march}. By using @option{-march} and
11917 @option{-mtune} together, it is possible to generate code that will
11918 run on a family of processors, but optimize the code for one
11919 particular member of that family.
11921 @samp{-mtune} defines the macros @samp{_MIPS_TUNE} and
11922 @samp{_MIPS_TUNE_@var{foo}}, which work in the same way as the
11923 @samp{-march} ones described above.
11927 Equivalent to @samp{-march=mips1}.
11931 Equivalent to @samp{-march=mips2}.
11935 Equivalent to @samp{-march=mips3}.
11939 Equivalent to @samp{-march=mips4}.
11943 Equivalent to @samp{-march=mips32}.
11947 Equivalent to @samp{-march=mips32r2}.
11951 Equivalent to @samp{-march=mips64}.
11956 @opindex mno-mips16
11957 Generate (do not generate) MIPS16 code. If GCC is targetting a
11958 MIPS32 or MIPS64 architecture, it will make use of the MIPS16e ASE@.
11960 MIPS16 code generation can also be controlled on a per-function basis
11961 by means of @code{mips16} and @code{nomips16} attributes.
11962 @xref{Function Attributes}, for more information.
11964 @item -mflip-mips16
11965 @opindex mflip-mips16
11966 Generate MIPS16 code on alternating functions. This option is provided
11967 for regression testing of mixed MIPS16/non-MIPS16 code generation, and is
11968 not intended for ordinary use in compiling user code.
11970 @item -minterlink-mips16
11971 @itemx -mno-interlink-mips16
11972 @opindex minterlink-mips16
11973 @opindex mno-interlink-mips16
11974 Require (do not require) that non-MIPS16 code be link-compatible with
11977 For example, non-MIPS16 code cannot jump directly to MIPS16 code;
11978 it must either use a call or an indirect jump. @option{-minterlink-mips16}
11979 therefore disables direct jumps unless GCC knows that the target of the
11980 jump is not MIPS16.
11992 Generate code for the given ABI@.
11994 Note that the EABI has a 32-bit and a 64-bit variant. GCC normally
11995 generates 64-bit code when you select a 64-bit architecture, but you
11996 can use @option{-mgp32} to get 32-bit code instead.
11998 For information about the O64 ABI, see
11999 @w{@uref{http://gcc.gnu.org/projects/mipso64-abi.html}}.
12001 GCC supports a variant of the o32 ABI in which floating-point registers
12002 are 64 rather than 32 bits wide. You can select this combination with
12003 @option{-mabi=32} @option{-mfp64}. This ABI relies on the @samp{mthc1}
12004 and @samp{mfhc1} instructions and is therefore only supported for
12005 MIPS32R2 processors.
12007 The register assignments for arguments and return values remain the
12008 same, but each scalar value is passed in a single 64-bit register
12009 rather than a pair of 32-bit registers. For example, scalar
12010 floating-point values are returned in @samp{$f0} only, not a
12011 @samp{$f0}/@samp{$f1} pair. The set of call-saved registers also
12012 remains the same, but all 64 bits are saved.
12015 @itemx -mno-abicalls
12017 @opindex mno-abicalls
12018 Generate (do not generate) code that is suitable for SVR4-style
12019 dynamic objects. @option{-mabicalls} is the default for SVR4-based
12024 Generate (do not generate) code that is fully position-independent,
12025 and that can therefore be linked into shared libraries. This option
12026 only affects @option{-mabicalls}.
12028 All @option{-mabicalls} code has traditionally been position-independent,
12029 regardless of options like @option{-fPIC} and @option{-fpic}. However,
12030 as an extension, the GNU toolchain allows executables to use absolute
12031 accesses for locally-binding symbols. It can also use shorter GP
12032 initialization sequences and generate direct calls to locally-defined
12033 functions. This mode is selected by @option{-mno-shared}.
12035 @option{-mno-shared} depends on binutils 2.16 or higher and generates
12036 objects that can only be linked by the GNU linker. However, the option
12037 does not affect the ABI of the final executable; it only affects the ABI
12038 of relocatable objects. Using @option{-mno-shared} will generally make
12039 executables both smaller and quicker.
12041 @option{-mshared} is the default.
12047 Lift (do not lift) the usual restrictions on the size of the global
12050 GCC normally uses a single instruction to load values from the GOT@.
12051 While this is relatively efficient, it will only work if the GOT
12052 is smaller than about 64k. Anything larger will cause the linker
12053 to report an error such as:
12055 @cindex relocation truncated to fit (MIPS)
12057 relocation truncated to fit: R_MIPS_GOT16 foobar
12060 If this happens, you should recompile your code with @option{-mxgot}.
12061 It should then work with very large GOTs, although it will also be
12062 less efficient, since it will take three instructions to fetch the
12063 value of a global symbol.
12065 Note that some linkers can create multiple GOTs. If you have such a
12066 linker, you should only need to use @option{-mxgot} when a single object
12067 file accesses more than 64k's worth of GOT entries. Very few do.
12069 These options have no effect unless GCC is generating position
12074 Assume that general-purpose registers are 32 bits wide.
12078 Assume that general-purpose registers are 64 bits wide.
12082 Assume that floating-point registers are 32 bits wide.
12086 Assume that floating-point registers are 64 bits wide.
12089 @opindex mhard-float
12090 Use floating-point coprocessor instructions.
12093 @opindex msoft-float
12094 Do not use floating-point coprocessor instructions. Implement
12095 floating-point calculations using library calls instead.
12097 @item -msingle-float
12098 @opindex msingle-float
12099 Assume that the floating-point coprocessor only supports single-precision
12102 @item -mdouble-float
12103 @opindex mdouble-float
12104 Assume that the floating-point coprocessor supports double-precision
12105 operations. This is the default.
12111 Use (do not use) @samp{ll}, @samp{sc}, and @samp{sync} instructions to
12112 implement atomic memory built-in functions. When neither option is
12113 specified, GCC will use the instructions if the target architecture
12116 @option{-mllsc} is useful if the runtime environment can emulate the
12117 instructions and @option{-mno-llsc} can be useful when compiling for
12118 nonstandard ISAs. You can make either option the default by
12119 configuring GCC with @option{--with-llsc} and @option{--without-llsc}
12120 respectively. @option{--with-llsc} is the default for some
12121 configurations; see the installation documentation for details.
12127 Use (do not use) revision 1 of the MIPS DSP ASE@.
12128 @xref{MIPS DSP Built-in Functions}. This option defines the
12129 preprocessor macro @samp{__mips_dsp}. It also defines
12130 @samp{__mips_dsp_rev} to 1.
12136 Use (do not use) revision 2 of the MIPS DSP ASE@.
12137 @xref{MIPS DSP Built-in Functions}. This option defines the
12138 preprocessor macros @samp{__mips_dsp} and @samp{__mips_dspr2}.
12139 It also defines @samp{__mips_dsp_rev} to 2.
12142 @itemx -mno-smartmips
12143 @opindex msmartmips
12144 @opindex mno-smartmips
12145 Use (do not use) the MIPS SmartMIPS ASE.
12147 @item -mpaired-single
12148 @itemx -mno-paired-single
12149 @opindex mpaired-single
12150 @opindex mno-paired-single
12151 Use (do not use) paired-single floating-point instructions.
12152 @xref{MIPS Paired-Single Support}. This option requires
12153 hardware floating-point support to be enabled.
12159 Use (do not use) MIPS Digital Media Extension instructions.
12160 This option can only be used when generating 64-bit code and requires
12161 hardware floating-point support to be enabled.
12166 @opindex mno-mips3d
12167 Use (do not use) the MIPS-3D ASE@. @xref{MIPS-3D Built-in Functions}.
12168 The option @option{-mips3d} implies @option{-mpaired-single}.
12174 Use (do not use) MT Multithreading instructions.
12178 Force @code{long} types to be 64 bits wide. See @option{-mlong32} for
12179 an explanation of the default and the way that the pointer size is
12184 Force @code{long}, @code{int}, and pointer types to be 32 bits wide.
12186 The default size of @code{int}s, @code{long}s and pointers depends on
12187 the ABI@. All the supported ABIs use 32-bit @code{int}s. The n64 ABI
12188 uses 64-bit @code{long}s, as does the 64-bit EABI; the others use
12189 32-bit @code{long}s. Pointers are the same size as @code{long}s,
12190 or the same size as integer registers, whichever is smaller.
12196 Assume (do not assume) that all symbols have 32-bit values, regardless
12197 of the selected ABI@. This option is useful in combination with
12198 @option{-mabi=64} and @option{-mno-abicalls} because it allows GCC
12199 to generate shorter and faster references to symbolic addresses.
12203 Put definitions of externally-visible data in a small data section
12204 if that data is no bigger than @var{num} bytes. GCC can then access
12205 the data more efficiently; see @option{-mgpopt} for details.
12207 The default @option{-G} option depends on the configuration.
12209 @item -mlocal-sdata
12210 @itemx -mno-local-sdata
12211 @opindex mlocal-sdata
12212 @opindex mno-local-sdata
12213 Extend (do not extend) the @option{-G} behavior to local data too,
12214 such as to static variables in C@. @option{-mlocal-sdata} is the
12215 default for all configurations.
12217 If the linker complains that an application is using too much small data,
12218 you might want to try rebuilding the less performance-critical parts with
12219 @option{-mno-local-sdata}. You might also want to build large
12220 libraries with @option{-mno-local-sdata}, so that the libraries leave
12221 more room for the main program.
12223 @item -mextern-sdata
12224 @itemx -mno-extern-sdata
12225 @opindex mextern-sdata
12226 @opindex mno-extern-sdata
12227 Assume (do not assume) that externally-defined data will be in
12228 a small data section if that data is within the @option{-G} limit.
12229 @option{-mextern-sdata} is the default for all configurations.
12231 If you compile a module @var{Mod} with @option{-mextern-sdata} @option{-G
12232 @var{num}} @option{-mgpopt}, and @var{Mod} references a variable @var{Var}
12233 that is no bigger than @var{num} bytes, you must make sure that @var{Var}
12234 is placed in a small data section. If @var{Var} is defined by another
12235 module, you must either compile that module with a high-enough
12236 @option{-G} setting or attach a @code{section} attribute to @var{Var}'s
12237 definition. If @var{Var} is common, you must link the application
12238 with a high-enough @option{-G} setting.
12240 The easiest way of satisfying these restrictions is to compile
12241 and link every module with the same @option{-G} option. However,
12242 you may wish to build a library that supports several different
12243 small data limits. You can do this by compiling the library with
12244 the highest supported @option{-G} setting and additionally using
12245 @option{-mno-extern-sdata} to stop the library from making assumptions
12246 about externally-defined data.
12252 Use (do not use) GP-relative accesses for symbols that are known to be
12253 in a small data section; see @option{-G}, @option{-mlocal-sdata} and
12254 @option{-mextern-sdata}. @option{-mgpopt} is the default for all
12257 @option{-mno-gpopt} is useful for cases where the @code{$gp} register
12258 might not hold the value of @code{_gp}. For example, if the code is
12259 part of a library that might be used in a boot monitor, programs that
12260 call boot monitor routines will pass an unknown value in @code{$gp}.
12261 (In such situations, the boot monitor itself would usually be compiled
12262 with @option{-G0}.)
12264 @option{-mno-gpopt} implies @option{-mno-local-sdata} and
12265 @option{-mno-extern-sdata}.
12267 @item -membedded-data
12268 @itemx -mno-embedded-data
12269 @opindex membedded-data
12270 @opindex mno-embedded-data
12271 Allocate variables to the read-only data section first if possible, then
12272 next in the small data section if possible, otherwise in data. This gives
12273 slightly slower code than the default, but reduces the amount of RAM required
12274 when executing, and thus may be preferred for some embedded systems.
12276 @item -muninit-const-in-rodata
12277 @itemx -mno-uninit-const-in-rodata
12278 @opindex muninit-const-in-rodata
12279 @opindex mno-uninit-const-in-rodata
12280 Put uninitialized @code{const} variables in the read-only data section.
12281 This option is only meaningful in conjunction with @option{-membedded-data}.
12283 @item -mcode-readable=@var{setting}
12284 @opindex mcode-readable
12285 Specify whether GCC may generate code that reads from executable sections.
12286 There are three possible settings:
12289 @item -mcode-readable=yes
12290 Instructions may freely access executable sections. This is the
12293 @item -mcode-readable=pcrel
12294 MIPS16 PC-relative load instructions can access executable sections,
12295 but other instructions must not do so. This option is useful on 4KSc
12296 and 4KSd processors when the code TLBs have the Read Inhibit bit set.
12297 It is also useful on processors that can be configured to have a dual
12298 instruction/data SRAM interface and that, like the M4K, automatically
12299 redirect PC-relative loads to the instruction RAM.
12301 @item -mcode-readable=no
12302 Instructions must not access executable sections. This option can be
12303 useful on targets that are configured to have a dual instruction/data
12304 SRAM interface but that (unlike the M4K) do not automatically redirect
12305 PC-relative loads to the instruction RAM.
12308 @item -msplit-addresses
12309 @itemx -mno-split-addresses
12310 @opindex msplit-addresses
12311 @opindex mno-split-addresses
12312 Enable (disable) use of the @code{%hi()} and @code{%lo()} assembler
12313 relocation operators. This option has been superseded by
12314 @option{-mexplicit-relocs} but is retained for backwards compatibility.
12316 @item -mexplicit-relocs
12317 @itemx -mno-explicit-relocs
12318 @opindex mexplicit-relocs
12319 @opindex mno-explicit-relocs
12320 Use (do not use) assembler relocation operators when dealing with symbolic
12321 addresses. The alternative, selected by @option{-mno-explicit-relocs},
12322 is to use assembler macros instead.
12324 @option{-mexplicit-relocs} is the default if GCC was configured
12325 to use an assembler that supports relocation operators.
12327 @item -mcheck-zero-division
12328 @itemx -mno-check-zero-division
12329 @opindex mcheck-zero-division
12330 @opindex mno-check-zero-division
12331 Trap (do not trap) on integer division by zero.
12333 The default is @option{-mcheck-zero-division}.
12335 @item -mdivide-traps
12336 @itemx -mdivide-breaks
12337 @opindex mdivide-traps
12338 @opindex mdivide-breaks
12339 MIPS systems check for division by zero by generating either a
12340 conditional trap or a break instruction. Using traps results in
12341 smaller code, but is only supported on MIPS II and later. Also, some
12342 versions of the Linux kernel have a bug that prevents trap from
12343 generating the proper signal (@code{SIGFPE}). Use @option{-mdivide-traps} to
12344 allow conditional traps on architectures that support them and
12345 @option{-mdivide-breaks} to force the use of breaks.
12347 The default is usually @option{-mdivide-traps}, but this can be
12348 overridden at configure time using @option{--with-divide=breaks}.
12349 Divide-by-zero checks can be completely disabled using
12350 @option{-mno-check-zero-division}.
12355 @opindex mno-memcpy
12356 Force (do not force) the use of @code{memcpy()} for non-trivial block
12357 moves. The default is @option{-mno-memcpy}, which allows GCC to inline
12358 most constant-sized copies.
12361 @itemx -mno-long-calls
12362 @opindex mlong-calls
12363 @opindex mno-long-calls
12364 Disable (do not disable) use of the @code{jal} instruction. Calling
12365 functions using @code{jal} is more efficient but requires the caller
12366 and callee to be in the same 256 megabyte segment.
12368 This option has no effect on abicalls code. The default is
12369 @option{-mno-long-calls}.
12375 Enable (disable) use of the @code{mad}, @code{madu} and @code{mul}
12376 instructions, as provided by the R4650 ISA@.
12379 @itemx -mno-fused-madd
12380 @opindex mfused-madd
12381 @opindex mno-fused-madd
12382 Enable (disable) use of the floating point multiply-accumulate
12383 instructions, when they are available. The default is
12384 @option{-mfused-madd}.
12386 When multiply-accumulate instructions are used, the intermediate
12387 product is calculated to infinite precision and is not subject to
12388 the FCSR Flush to Zero bit. This may be undesirable in some
12393 Tell the MIPS assembler to not run its preprocessor over user
12394 assembler files (with a @samp{.s} suffix) when assembling them.
12397 @itemx -mno-fix-r4000
12398 @opindex mfix-r4000
12399 @opindex mno-fix-r4000
12400 Work around certain R4000 CPU errata:
12403 A double-word or a variable shift may give an incorrect result if executed
12404 immediately after starting an integer division.
12406 A double-word or a variable shift may give an incorrect result if executed
12407 while an integer multiplication is in progress.
12409 An integer division may give an incorrect result if started in a delay slot
12410 of a taken branch or a jump.
12414 @itemx -mno-fix-r4400
12415 @opindex mfix-r4400
12416 @opindex mno-fix-r4400
12417 Work around certain R4400 CPU errata:
12420 A double-word or a variable shift may give an incorrect result if executed
12421 immediately after starting an integer division.
12425 @itemx -mno-fix-vr4120
12426 @opindex mfix-vr4120
12427 Work around certain VR4120 errata:
12430 @code{dmultu} does not always produce the correct result.
12432 @code{div} and @code{ddiv} do not always produce the correct result if one
12433 of the operands is negative.
12435 The workarounds for the division errata rely on special functions in
12436 @file{libgcc.a}. At present, these functions are only provided by
12437 the @code{mips64vr*-elf} configurations.
12439 Other VR4120 errata require a nop to be inserted between certain pairs of
12440 instructions. These errata are handled by the assembler, not by GCC itself.
12443 @opindex mfix-vr4130
12444 Work around the VR4130 @code{mflo}/@code{mfhi} errata. The
12445 workarounds are implemented by the assembler rather than by GCC,
12446 although GCC will avoid using @code{mflo} and @code{mfhi} if the
12447 VR4130 @code{macc}, @code{macchi}, @code{dmacc} and @code{dmacchi}
12448 instructions are available instead.
12451 @itemx -mno-fix-sb1
12453 Work around certain SB-1 CPU core errata.
12454 (This flag currently works around the SB-1 revision 2
12455 ``F1'' and ``F2'' floating point errata.)
12457 @item -mflush-func=@var{func}
12458 @itemx -mno-flush-func
12459 @opindex mflush-func
12460 Specifies the function to call to flush the I and D caches, or to not
12461 call any such function. If called, the function must take the same
12462 arguments as the common @code{_flush_func()}, that is, the address of the
12463 memory range for which the cache is being flushed, the size of the
12464 memory range, and the number 3 (to flush both caches). The default
12465 depends on the target GCC was configured for, but commonly is either
12466 @samp{_flush_func} or @samp{__cpu_flush}.
12468 @item mbranch-cost=@var{num}
12469 @opindex mbranch-cost
12470 Set the cost of branches to roughly @var{num} ``simple'' instructions.
12471 This cost is only a heuristic and is not guaranteed to produce
12472 consistent results across releases. A zero cost redundantly selects
12473 the default, which is based on the @option{-mtune} setting.
12475 @item -mbranch-likely
12476 @itemx -mno-branch-likely
12477 @opindex mbranch-likely
12478 @opindex mno-branch-likely
12479 Enable or disable use of Branch Likely instructions, regardless of the
12480 default for the selected architecture. By default, Branch Likely
12481 instructions may be generated if they are supported by the selected
12482 architecture. An exception is for the MIPS32 and MIPS64 architectures
12483 and processors which implement those architectures; for those, Branch
12484 Likely instructions will not be generated by default because the MIPS32
12485 and MIPS64 architectures specifically deprecate their use.
12487 @item -mfp-exceptions
12488 @itemx -mno-fp-exceptions
12489 @opindex mfp-exceptions
12490 Specifies whether FP exceptions are enabled. This affects how we schedule
12491 FP instructions for some processors. The default is that FP exceptions are
12494 For instance, on the SB-1, if FP exceptions are disabled, and we are emitting
12495 64-bit code, then we can use both FP pipes. Otherwise, we can only use one
12498 @item -mvr4130-align
12499 @itemx -mno-vr4130-align
12500 @opindex mvr4130-align
12501 The VR4130 pipeline is two-way superscalar, but can only issue two
12502 instructions together if the first one is 8-byte aligned. When this
12503 option is enabled, GCC will align pairs of instructions that it
12504 thinks should execute in parallel.
12506 This option only has an effect when optimizing for the VR4130.
12507 It normally makes code faster, but at the expense of making it bigger.
12508 It is enabled by default at optimization level @option{-O3}.
12512 @subsection MMIX Options
12513 @cindex MMIX Options
12515 These options are defined for the MMIX:
12519 @itemx -mno-libfuncs
12521 @opindex mno-libfuncs
12522 Specify that intrinsic library functions are being compiled, passing all
12523 values in registers, no matter the size.
12526 @itemx -mno-epsilon
12528 @opindex mno-epsilon
12529 Generate floating-point comparison instructions that compare with respect
12530 to the @code{rE} epsilon register.
12532 @item -mabi=mmixware
12534 @opindex mabi-mmixware
12536 Generate code that passes function parameters and return values that (in
12537 the called function) are seen as registers @code{$0} and up, as opposed to
12538 the GNU ABI which uses global registers @code{$231} and up.
12540 @item -mzero-extend
12541 @itemx -mno-zero-extend
12542 @opindex mzero-extend
12543 @opindex mno-zero-extend
12544 When reading data from memory in sizes shorter than 64 bits, use (do not
12545 use) zero-extending load instructions by default, rather than
12546 sign-extending ones.
12549 @itemx -mno-knuthdiv
12551 @opindex mno-knuthdiv
12552 Make the result of a division yielding a remainder have the same sign as
12553 the divisor. With the default, @option{-mno-knuthdiv}, the sign of the
12554 remainder follows the sign of the dividend. Both methods are
12555 arithmetically valid, the latter being almost exclusively used.
12557 @item -mtoplevel-symbols
12558 @itemx -mno-toplevel-symbols
12559 @opindex mtoplevel-symbols
12560 @opindex mno-toplevel-symbols
12561 Prepend (do not prepend) a @samp{:} to all global symbols, so the assembly
12562 code can be used with the @code{PREFIX} assembly directive.
12566 Generate an executable in the ELF format, rather than the default
12567 @samp{mmo} format used by the @command{mmix} simulator.
12569 @item -mbranch-predict
12570 @itemx -mno-branch-predict
12571 @opindex mbranch-predict
12572 @opindex mno-branch-predict
12573 Use (do not use) the probable-branch instructions, when static branch
12574 prediction indicates a probable branch.
12576 @item -mbase-addresses
12577 @itemx -mno-base-addresses
12578 @opindex mbase-addresses
12579 @opindex mno-base-addresses
12580 Generate (do not generate) code that uses @emph{base addresses}. Using a
12581 base address automatically generates a request (handled by the assembler
12582 and the linker) for a constant to be set up in a global register. The
12583 register is used for one or more base address requests within the range 0
12584 to 255 from the value held in the register. The generally leads to short
12585 and fast code, but the number of different data items that can be
12586 addressed is limited. This means that a program that uses lots of static
12587 data may require @option{-mno-base-addresses}.
12589 @item -msingle-exit
12590 @itemx -mno-single-exit
12591 @opindex msingle-exit
12592 @opindex mno-single-exit
12593 Force (do not force) generated code to have a single exit point in each
12597 @node MN10300 Options
12598 @subsection MN10300 Options
12599 @cindex MN10300 options
12601 These @option{-m} options are defined for Matsushita MN10300 architectures:
12606 Generate code to avoid bugs in the multiply instructions for the MN10300
12607 processors. This is the default.
12609 @item -mno-mult-bug
12610 @opindex mno-mult-bug
12611 Do not generate code to avoid bugs in the multiply instructions for the
12612 MN10300 processors.
12616 Generate code which uses features specific to the AM33 processor.
12620 Do not generate code which uses features specific to the AM33 processor. This
12623 @item -mreturn-pointer-on-d0
12624 @opindex mreturn-pointer-on-d0
12625 When generating a function which returns a pointer, return the pointer
12626 in both @code{a0} and @code{d0}. Otherwise, the pointer is returned
12627 only in a0, and attempts to call such functions without a prototype
12628 would result in errors. Note that this option is on by default; use
12629 @option{-mno-return-pointer-on-d0} to disable it.
12633 Do not link in the C run-time initialization object file.
12637 Indicate to the linker that it should perform a relaxation optimization pass
12638 to shorten branches, calls and absolute memory addresses. This option only
12639 has an effect when used on the command line for the final link step.
12641 This option makes symbolic debugging impossible.
12645 @subsection MT Options
12648 These @option{-m} options are defined for Morpho MT architectures:
12652 @item -march=@var{cpu-type}
12654 Generate code that will run on @var{cpu-type}, which is the name of a system
12655 representing a certain processor type. Possible values for
12656 @var{cpu-type} are @samp{ms1-64-001}, @samp{ms1-16-002},
12657 @samp{ms1-16-003} and @samp{ms2}.
12659 When this option is not used, the default is @option{-march=ms1-16-002}.
12663 Use byte loads and stores when generating code.
12667 Do not use byte loads and stores when generating code.
12671 Use simulator runtime
12675 Do not link in the C run-time initialization object file
12676 @file{crti.o}. Other run-time initialization and termination files
12677 such as @file{startup.o} and @file{exit.o} are still included on the
12678 linker command line.
12682 @node PDP-11 Options
12683 @subsection PDP-11 Options
12684 @cindex PDP-11 Options
12686 These options are defined for the PDP-11:
12691 Use hardware FPP floating point. This is the default. (FIS floating
12692 point on the PDP-11/40 is not supported.)
12695 @opindex msoft-float
12696 Do not use hardware floating point.
12700 Return floating-point results in ac0 (fr0 in Unix assembler syntax).
12704 Return floating-point results in memory. This is the default.
12708 Generate code for a PDP-11/40.
12712 Generate code for a PDP-11/45. This is the default.
12716 Generate code for a PDP-11/10.
12718 @item -mbcopy-builtin
12719 @opindex bcopy-builtin
12720 Use inline @code{movmemhi} patterns for copying memory. This is the
12725 Do not use inline @code{movmemhi} patterns for copying memory.
12731 Use 16-bit @code{int}. This is the default.
12737 Use 32-bit @code{int}.
12740 @itemx -mno-float32
12742 @opindex mno-float32
12743 Use 64-bit @code{float}. This is the default.
12746 @itemx -mno-float64
12748 @opindex mno-float64
12749 Use 32-bit @code{float}.
12753 Use @code{abshi2} pattern. This is the default.
12757 Do not use @code{abshi2} pattern.
12759 @item -mbranch-expensive
12760 @opindex mbranch-expensive
12761 Pretend that branches are expensive. This is for experimenting with
12762 code generation only.
12764 @item -mbranch-cheap
12765 @opindex mbranch-cheap
12766 Do not pretend that branches are expensive. This is the default.
12770 Generate code for a system with split I&D@.
12774 Generate code for a system without split I&D@. This is the default.
12778 Use Unix assembler syntax. This is the default when configured for
12779 @samp{pdp11-*-bsd}.
12783 Use DEC assembler syntax. This is the default when configured for any
12784 PDP-11 target other than @samp{pdp11-*-bsd}.
12787 @node PowerPC Options
12788 @subsection PowerPC Options
12789 @cindex PowerPC options
12791 These are listed under @xref{RS/6000 and PowerPC Options}.
12793 @node RS/6000 and PowerPC Options
12794 @subsection IBM RS/6000 and PowerPC Options
12795 @cindex RS/6000 and PowerPC Options
12796 @cindex IBM RS/6000 and PowerPC Options
12798 These @samp{-m} options are defined for the IBM RS/6000 and PowerPC:
12805 @itemx -mno-powerpc
12806 @itemx -mpowerpc-gpopt
12807 @itemx -mno-powerpc-gpopt
12808 @itemx -mpowerpc-gfxopt
12809 @itemx -mno-powerpc-gfxopt
12811 @itemx -mno-powerpc64
12815 @itemx -mno-popcntb
12823 @itemx -mno-hard-dfp
12827 @opindex mno-power2
12829 @opindex mno-powerpc
12830 @opindex mpowerpc-gpopt
12831 @opindex mno-powerpc-gpopt
12832 @opindex mpowerpc-gfxopt
12833 @opindex mno-powerpc-gfxopt
12834 @opindex mpowerpc64
12835 @opindex mno-powerpc64
12839 @opindex mno-popcntb
12845 @opindex mno-mfpgpr
12847 @opindex mno-hard-dfp
12848 GCC supports two related instruction set architectures for the
12849 RS/6000 and PowerPC@. The @dfn{POWER} instruction set are those
12850 instructions supported by the @samp{rios} chip set used in the original
12851 RS/6000 systems and the @dfn{PowerPC} instruction set is the
12852 architecture of the Freescale MPC5xx, MPC6xx, MPC8xx microprocessors, and
12853 the IBM 4xx, 6xx, and follow-on microprocessors.
12855 Neither architecture is a subset of the other. However there is a
12856 large common subset of instructions supported by both. An MQ
12857 register is included in processors supporting the POWER architecture.
12859 You use these options to specify which instructions are available on the
12860 processor you are using. The default value of these options is
12861 determined when configuring GCC@. Specifying the
12862 @option{-mcpu=@var{cpu_type}} overrides the specification of these
12863 options. We recommend you use the @option{-mcpu=@var{cpu_type}} option
12864 rather than the options listed above.
12866 The @option{-mpower} option allows GCC to generate instructions that
12867 are found only in the POWER architecture and to use the MQ register.
12868 Specifying @option{-mpower2} implies @option{-power} and also allows GCC
12869 to generate instructions that are present in the POWER2 architecture but
12870 not the original POWER architecture.
12872 The @option{-mpowerpc} option allows GCC to generate instructions that
12873 are found only in the 32-bit subset of the PowerPC architecture.
12874 Specifying @option{-mpowerpc-gpopt} implies @option{-mpowerpc} and also allows
12875 GCC to use the optional PowerPC architecture instructions in the
12876 General Purpose group, including floating-point square root. Specifying
12877 @option{-mpowerpc-gfxopt} implies @option{-mpowerpc} and also allows GCC to
12878 use the optional PowerPC architecture instructions in the Graphics
12879 group, including floating-point select.
12881 The @option{-mmfcrf} option allows GCC to generate the move from
12882 condition register field instruction implemented on the POWER4
12883 processor and other processors that support the PowerPC V2.01
12885 The @option{-mpopcntb} option allows GCC to generate the popcount and
12886 double precision FP reciprocal estimate instruction implemented on the
12887 POWER5 processor and other processors that support the PowerPC V2.02
12889 The @option{-mfprnd} option allows GCC to generate the FP round to
12890 integer instructions implemented on the POWER5+ processor and other
12891 processors that support the PowerPC V2.03 architecture.
12892 The @option{-mcmpb} option allows GCC to generate the compare bytes
12893 instruction implemented on the POWER6 processor and other processors
12894 that support the PowerPC V2.05 architecture.
12895 The @option{-mmfpgpr} option allows GCC to generate the FP move to/from
12896 general purpose register instructions implemented on the POWER6X
12897 processor and other processors that support the extended PowerPC V2.05
12899 The @option{-mhard-dfp} option allows GCC to generate the decimal floating
12900 point instructions implemented on some POWER processors.
12902 The @option{-mpowerpc64} option allows GCC to generate the additional
12903 64-bit instructions that are found in the full PowerPC64 architecture
12904 and to treat GPRs as 64-bit, doubleword quantities. GCC defaults to
12905 @option{-mno-powerpc64}.
12907 If you specify both @option{-mno-power} and @option{-mno-powerpc}, GCC
12908 will use only the instructions in the common subset of both
12909 architectures plus some special AIX common-mode calls, and will not use
12910 the MQ register. Specifying both @option{-mpower} and @option{-mpowerpc}
12911 permits GCC to use any instruction from either architecture and to
12912 allow use of the MQ register; specify this for the Motorola MPC601.
12914 @item -mnew-mnemonics
12915 @itemx -mold-mnemonics
12916 @opindex mnew-mnemonics
12917 @opindex mold-mnemonics
12918 Select which mnemonics to use in the generated assembler code. With
12919 @option{-mnew-mnemonics}, GCC uses the assembler mnemonics defined for
12920 the PowerPC architecture. With @option{-mold-mnemonics} it uses the
12921 assembler mnemonics defined for the POWER architecture. Instructions
12922 defined in only one architecture have only one mnemonic; GCC uses that
12923 mnemonic irrespective of which of these options is specified.
12925 GCC defaults to the mnemonics appropriate for the architecture in
12926 use. Specifying @option{-mcpu=@var{cpu_type}} sometimes overrides the
12927 value of these option. Unless you are building a cross-compiler, you
12928 should normally not specify either @option{-mnew-mnemonics} or
12929 @option{-mold-mnemonics}, but should instead accept the default.
12931 @item -mcpu=@var{cpu_type}
12933 Set architecture type, register usage, choice of mnemonics, and
12934 instruction scheduling parameters for machine type @var{cpu_type}.
12935 Supported values for @var{cpu_type} are @samp{401}, @samp{403},
12936 @samp{405}, @samp{405fp}, @samp{440}, @samp{440fp}, @samp{505},
12937 @samp{601}, @samp{602}, @samp{603}, @samp{603e}, @samp{604},
12938 @samp{604e}, @samp{620}, @samp{630}, @samp{740}, @samp{7400},
12939 @samp{7450}, @samp{750}, @samp{801}, @samp{821}, @samp{823},
12940 @samp{860}, @samp{970}, @samp{8540}, @samp{e300c2}, @samp{e300c3},
12941 @samp{ec603e}, @samp{G3}, @samp{G4}, @samp{G5}, @samp{power},
12942 @samp{power2}, @samp{power3}, @samp{power4}, @samp{power5},
12943 @samp{power5+}, @samp{power6}, @samp{power6x}, @samp{common},
12944 @samp{powerpc}, @samp{powerpc64}, @samp{rios}, @samp{rios1},
12945 @samp{rios2}, @samp{rsc}, and @samp{rs64}.
12947 @option{-mcpu=common} selects a completely generic processor. Code
12948 generated under this option will run on any POWER or PowerPC processor.
12949 GCC will use only the instructions in the common subset of both
12950 architectures, and will not use the MQ register. GCC assumes a generic
12951 processor model for scheduling purposes.
12953 @option{-mcpu=power}, @option{-mcpu=power2}, @option{-mcpu=powerpc}, and
12954 @option{-mcpu=powerpc64} specify generic POWER, POWER2, pure 32-bit
12955 PowerPC (i.e., not MPC601), and 64-bit PowerPC architecture machine
12956 types, with an appropriate, generic processor model assumed for
12957 scheduling purposes.
12959 The other options specify a specific processor. Code generated under
12960 those options will run best on that processor, and may not run at all on
12963 The @option{-mcpu} options automatically enable or disable the
12966 @gccoptlist{-maltivec -mfprnd -mhard-float -mmfcrf -mmultiple @gol
12967 -mnew-mnemonics -mpopcntb -mpower -mpower2 -mpowerpc64 @gol
12968 -mpowerpc-gpopt -mpowerpc-gfxopt -mstring -mmulhw -mdlmzb -mmfpgpr}
12970 The particular options set for any particular CPU will vary between
12971 compiler versions, depending on what setting seems to produce optimal
12972 code for that CPU; it doesn't necessarily reflect the actual hardware's
12973 capabilities. If you wish to set an individual option to a particular
12974 value, you may specify it after the @option{-mcpu} option, like
12975 @samp{-mcpu=970 -mno-altivec}.
12977 On AIX, the @option{-maltivec} and @option{-mpowerpc64} options are
12978 not enabled or disabled by the @option{-mcpu} option at present because
12979 AIX does not have full support for these options. You may still
12980 enable or disable them individually if you're sure it'll work in your
12983 @item -mtune=@var{cpu_type}
12985 Set the instruction scheduling parameters for machine type
12986 @var{cpu_type}, but do not set the architecture type, register usage, or
12987 choice of mnemonics, as @option{-mcpu=@var{cpu_type}} would. The same
12988 values for @var{cpu_type} are used for @option{-mtune} as for
12989 @option{-mcpu}. If both are specified, the code generated will use the
12990 architecture, registers, and mnemonics set by @option{-mcpu}, but the
12991 scheduling parameters set by @option{-mtune}.
12997 Generate code to compute division as reciprocal estimate and iterative
12998 refinement, creating opportunities for increased throughput. This
12999 feature requires: optional PowerPC Graphics instruction set for single
13000 precision and FRE instruction for double precision, assuming divides
13001 cannot generate user-visible traps, and the domain values not include
13002 Infinities, denormals or zero denominator.
13005 @itemx -mno-altivec
13007 @opindex mno-altivec
13008 Generate code that uses (does not use) AltiVec instructions, and also
13009 enable the use of built-in functions that allow more direct access to
13010 the AltiVec instruction set. You may also need to set
13011 @option{-mabi=altivec} to adjust the current ABI with AltiVec ABI
13017 @opindex mno-vrsave
13018 Generate VRSAVE instructions when generating AltiVec code.
13021 @opindex msecure-plt
13022 Generate code that allows ld and ld.so to build executables and shared
13023 libraries with non-exec .plt and .got sections. This is a PowerPC
13024 32-bit SYSV ABI option.
13028 Generate code that uses a BSS .plt section that ld.so fills in, and
13029 requires .plt and .got sections that are both writable and executable.
13030 This is a PowerPC 32-bit SYSV ABI option.
13036 This switch enables or disables the generation of ISEL instructions.
13038 @item -misel=@var{yes/no}
13039 This switch has been deprecated. Use @option{-misel} and
13040 @option{-mno-isel} instead.
13046 This switch enables or disables the generation of SPE simd
13052 @opindex mno-paired
13053 This switch enables or disables the generation of PAIRED simd
13056 @item -mspe=@var{yes/no}
13057 This option has been deprecated. Use @option{-mspe} and
13058 @option{-mno-spe} instead.
13060 @item -mfloat-gprs=@var{yes/single/double/no}
13061 @itemx -mfloat-gprs
13062 @opindex mfloat-gprs
13063 This switch enables or disables the generation of floating point
13064 operations on the general purpose registers for architectures that
13067 The argument @var{yes} or @var{single} enables the use of
13068 single-precision floating point operations.
13070 The argument @var{double} enables the use of single and
13071 double-precision floating point operations.
13073 The argument @var{no} disables floating point operations on the
13074 general purpose registers.
13076 This option is currently only available on the MPC854x.
13082 Generate code for 32-bit or 64-bit environments of Darwin and SVR4
13083 targets (including GNU/Linux). The 32-bit environment sets int, long
13084 and pointer to 32 bits and generates code that runs on any PowerPC
13085 variant. The 64-bit environment sets int to 32 bits and long and
13086 pointer to 64 bits, and generates code for PowerPC64, as for
13087 @option{-mpowerpc64}.
13090 @itemx -mno-fp-in-toc
13091 @itemx -mno-sum-in-toc
13092 @itemx -mminimal-toc
13094 @opindex mno-fp-in-toc
13095 @opindex mno-sum-in-toc
13096 @opindex mminimal-toc
13097 Modify generation of the TOC (Table Of Contents), which is created for
13098 every executable file. The @option{-mfull-toc} option is selected by
13099 default. In that case, GCC will allocate at least one TOC entry for
13100 each unique non-automatic variable reference in your program. GCC
13101 will also place floating-point constants in the TOC@. However, only
13102 16,384 entries are available in the TOC@.
13104 If you receive a linker error message that saying you have overflowed
13105 the available TOC space, you can reduce the amount of TOC space used
13106 with the @option{-mno-fp-in-toc} and @option{-mno-sum-in-toc} options.
13107 @option{-mno-fp-in-toc} prevents GCC from putting floating-point
13108 constants in the TOC and @option{-mno-sum-in-toc} forces GCC to
13109 generate code to calculate the sum of an address and a constant at
13110 run-time instead of putting that sum into the TOC@. You may specify one
13111 or both of these options. Each causes GCC to produce very slightly
13112 slower and larger code at the expense of conserving TOC space.
13114 If you still run out of space in the TOC even when you specify both of
13115 these options, specify @option{-mminimal-toc} instead. This option causes
13116 GCC to make only one TOC entry for every file. When you specify this
13117 option, GCC will produce code that is slower and larger but which
13118 uses extremely little TOC space. You may wish to use this option
13119 only on files that contain less frequently executed code.
13125 Enable 64-bit AIX ABI and calling convention: 64-bit pointers, 64-bit
13126 @code{long} type, and the infrastructure needed to support them.
13127 Specifying @option{-maix64} implies @option{-mpowerpc64} and
13128 @option{-mpowerpc}, while @option{-maix32} disables the 64-bit ABI and
13129 implies @option{-mno-powerpc64}. GCC defaults to @option{-maix32}.
13132 @itemx -mno-xl-compat
13133 @opindex mxl-compat
13134 @opindex mno-xl-compat
13135 Produce code that conforms more closely to IBM XL compiler semantics
13136 when using AIX-compatible ABI@. Pass floating-point arguments to
13137 prototyped functions beyond the register save area (RSA) on the stack
13138 in addition to argument FPRs. Do not assume that most significant
13139 double in 128-bit long double value is properly rounded when comparing
13140 values and converting to double. Use XL symbol names for long double
13143 The AIX calling convention was extended but not initially documented to
13144 handle an obscure K&R C case of calling a function that takes the
13145 address of its arguments with fewer arguments than declared. IBM XL
13146 compilers access floating point arguments which do not fit in the
13147 RSA from the stack when a subroutine is compiled without
13148 optimization. Because always storing floating-point arguments on the
13149 stack is inefficient and rarely needed, this option is not enabled by
13150 default and only is necessary when calling subroutines compiled by IBM
13151 XL compilers without optimization.
13155 Support @dfn{IBM RS/6000 SP} @dfn{Parallel Environment} (PE)@. Link an
13156 application written to use message passing with special startup code to
13157 enable the application to run. The system must have PE installed in the
13158 standard location (@file{/usr/lpp/ppe.poe/}), or the @file{specs} file
13159 must be overridden with the @option{-specs=} option to specify the
13160 appropriate directory location. The Parallel Environment does not
13161 support threads, so the @option{-mpe} option and the @option{-pthread}
13162 option are incompatible.
13164 @item -malign-natural
13165 @itemx -malign-power
13166 @opindex malign-natural
13167 @opindex malign-power
13168 On AIX, 32-bit Darwin, and 64-bit PowerPC GNU/Linux, the option
13169 @option{-malign-natural} overrides the ABI-defined alignment of larger
13170 types, such as floating-point doubles, on their natural size-based boundary.
13171 The option @option{-malign-power} instructs GCC to follow the ABI-specified
13172 alignment rules. GCC defaults to the standard alignment defined in the ABI@.
13174 On 64-bit Darwin, natural alignment is the default, and @option{-malign-power}
13178 @itemx -mhard-float
13179 @opindex msoft-float
13180 @opindex mhard-float
13181 Generate code that does not use (uses) the floating-point register set.
13182 Software floating point emulation is provided if you use the
13183 @option{-msoft-float} option, and pass the option to GCC when linking.
13186 @itemx -mno-multiple
13188 @opindex mno-multiple
13189 Generate code that uses (does not use) the load multiple word
13190 instructions and the store multiple word instructions. These
13191 instructions are generated by default on POWER systems, and not
13192 generated on PowerPC systems. Do not use @option{-mmultiple} on little
13193 endian PowerPC systems, since those instructions do not work when the
13194 processor is in little endian mode. The exceptions are PPC740 and
13195 PPC750 which permit the instructions usage in little endian mode.
13200 @opindex mno-string
13201 Generate code that uses (does not use) the load string instructions
13202 and the store string word instructions to save multiple registers and
13203 do small block moves. These instructions are generated by default on
13204 POWER systems, and not generated on PowerPC systems. Do not use
13205 @option{-mstring} on little endian PowerPC systems, since those
13206 instructions do not work when the processor is in little endian mode.
13207 The exceptions are PPC740 and PPC750 which permit the instructions
13208 usage in little endian mode.
13213 @opindex mno-update
13214 Generate code that uses (does not use) the load or store instructions
13215 that update the base register to the address of the calculated memory
13216 location. These instructions are generated by default. If you use
13217 @option{-mno-update}, there is a small window between the time that the
13218 stack pointer is updated and the address of the previous frame is
13219 stored, which means code that walks the stack frame across interrupts or
13220 signals may get corrupted data.
13223 @itemx -mno-fused-madd
13224 @opindex mfused-madd
13225 @opindex mno-fused-madd
13226 Generate code that uses (does not use) the floating point multiply and
13227 accumulate instructions. These instructions are generated by default if
13228 hardware floating is used.
13234 Generate code that uses (does not use) the half-word multiply and
13235 multiply-accumulate instructions on the IBM 405 and 440 processors.
13236 These instructions are generated by default when targetting those
13243 Generate code that uses (does not use) the string-search @samp{dlmzb}
13244 instruction on the IBM 405 and 440 processors. This instruction is
13245 generated by default when targetting those processors.
13247 @item -mno-bit-align
13249 @opindex mno-bit-align
13250 @opindex mbit-align
13251 On System V.4 and embedded PowerPC systems do not (do) force structures
13252 and unions that contain bit-fields to be aligned to the base type of the
13255 For example, by default a structure containing nothing but 8
13256 @code{unsigned} bit-fields of length 1 would be aligned to a 4 byte
13257 boundary and have a size of 4 bytes. By using @option{-mno-bit-align},
13258 the structure would be aligned to a 1 byte boundary and be one byte in
13261 @item -mno-strict-align
13262 @itemx -mstrict-align
13263 @opindex mno-strict-align
13264 @opindex mstrict-align
13265 On System V.4 and embedded PowerPC systems do not (do) assume that
13266 unaligned memory references will be handled by the system.
13268 @item -mrelocatable
13269 @itemx -mno-relocatable
13270 @opindex mrelocatable
13271 @opindex mno-relocatable
13272 On embedded PowerPC systems generate code that allows (does not allow)
13273 the program to be relocated to a different address at runtime. If you
13274 use @option{-mrelocatable} on any module, all objects linked together must
13275 be compiled with @option{-mrelocatable} or @option{-mrelocatable-lib}.
13277 @item -mrelocatable-lib
13278 @itemx -mno-relocatable-lib
13279 @opindex mrelocatable-lib
13280 @opindex mno-relocatable-lib
13281 On embedded PowerPC systems generate code that allows (does not allow)
13282 the program to be relocated to a different address at runtime. Modules
13283 compiled with @option{-mrelocatable-lib} can be linked with either modules
13284 compiled without @option{-mrelocatable} and @option{-mrelocatable-lib} or
13285 with modules compiled with the @option{-mrelocatable} options.
13291 On System V.4 and embedded PowerPC systems do not (do) assume that
13292 register 2 contains a pointer to a global area pointing to the addresses
13293 used in the program.
13296 @itemx -mlittle-endian
13298 @opindex mlittle-endian
13299 On System V.4 and embedded PowerPC systems compile code for the
13300 processor in little endian mode. The @option{-mlittle-endian} option is
13301 the same as @option{-mlittle}.
13304 @itemx -mbig-endian
13306 @opindex mbig-endian
13307 On System V.4 and embedded PowerPC systems compile code for the
13308 processor in big endian mode. The @option{-mbig-endian} option is
13309 the same as @option{-mbig}.
13311 @item -mdynamic-no-pic
13312 @opindex mdynamic-no-pic
13313 On Darwin and Mac OS X systems, compile code so that it is not
13314 relocatable, but that its external references are relocatable. The
13315 resulting code is suitable for applications, but not shared
13318 @item -mprioritize-restricted-insns=@var{priority}
13319 @opindex mprioritize-restricted-insns
13320 This option controls the priority that is assigned to
13321 dispatch-slot restricted instructions during the second scheduling
13322 pass. The argument @var{priority} takes the value @var{0/1/2} to assign
13323 @var{no/highest/second-highest} priority to dispatch slot restricted
13326 @item -msched-costly-dep=@var{dependence_type}
13327 @opindex msched-costly-dep
13328 This option controls which dependences are considered costly
13329 by the target during instruction scheduling. The argument
13330 @var{dependence_type} takes one of the following values:
13331 @var{no}: no dependence is costly,
13332 @var{all}: all dependences are costly,
13333 @var{true_store_to_load}: a true dependence from store to load is costly,
13334 @var{store_to_load}: any dependence from store to load is costly,
13335 @var{number}: any dependence which latency >= @var{number} is costly.
13337 @item -minsert-sched-nops=@var{scheme}
13338 @opindex minsert-sched-nops
13339 This option controls which nop insertion scheme will be used during
13340 the second scheduling pass. The argument @var{scheme} takes one of the
13342 @var{no}: Don't insert nops.
13343 @var{pad}: Pad with nops any dispatch group which has vacant issue slots,
13344 according to the scheduler's grouping.
13345 @var{regroup_exact}: Insert nops to force costly dependent insns into
13346 separate groups. Insert exactly as many nops as needed to force an insn
13347 to a new group, according to the estimated processor grouping.
13348 @var{number}: Insert nops to force costly dependent insns into
13349 separate groups. Insert @var{number} nops to force an insn to a new group.
13352 @opindex mcall-sysv
13353 On System V.4 and embedded PowerPC systems compile code using calling
13354 conventions that adheres to the March 1995 draft of the System V
13355 Application Binary Interface, PowerPC processor supplement. This is the
13356 default unless you configured GCC using @samp{powerpc-*-eabiaix}.
13358 @item -mcall-sysv-eabi
13359 @opindex mcall-sysv-eabi
13360 Specify both @option{-mcall-sysv} and @option{-meabi} options.
13362 @item -mcall-sysv-noeabi
13363 @opindex mcall-sysv-noeabi
13364 Specify both @option{-mcall-sysv} and @option{-mno-eabi} options.
13366 @item -mcall-solaris
13367 @opindex mcall-solaris
13368 On System V.4 and embedded PowerPC systems compile code for the Solaris
13372 @opindex mcall-linux
13373 On System V.4 and embedded PowerPC systems compile code for the
13374 Linux-based GNU system.
13378 On System V.4 and embedded PowerPC systems compile code for the
13379 Hurd-based GNU system.
13381 @item -mcall-netbsd
13382 @opindex mcall-netbsd
13383 On System V.4 and embedded PowerPC systems compile code for the
13384 NetBSD operating system.
13386 @item -maix-struct-return
13387 @opindex maix-struct-return
13388 Return all structures in memory (as specified by the AIX ABI)@.
13390 @item -msvr4-struct-return
13391 @opindex msvr4-struct-return
13392 Return structures smaller than 8 bytes in registers (as specified by the
13395 @item -mabi=@var{abi-type}
13397 Extend the current ABI with a particular extension, or remove such extension.
13398 Valid values are @var{altivec}, @var{no-altivec}, @var{spe},
13399 @var{no-spe}, @var{ibmlongdouble}, @var{ieeelongdouble}@.
13403 Extend the current ABI with SPE ABI extensions. This does not change
13404 the default ABI, instead it adds the SPE ABI extensions to the current
13408 @opindex mabi=no-spe
13409 Disable Booke SPE ABI extensions for the current ABI@.
13411 @item -mabi=ibmlongdouble
13412 @opindex mabi=ibmlongdouble
13413 Change the current ABI to use IBM extended precision long double.
13414 This is a PowerPC 32-bit SYSV ABI option.
13416 @item -mabi=ieeelongdouble
13417 @opindex mabi=ieeelongdouble
13418 Change the current ABI to use IEEE extended precision long double.
13419 This is a PowerPC 32-bit Linux ABI option.
13422 @itemx -mno-prototype
13423 @opindex mprototype
13424 @opindex mno-prototype
13425 On System V.4 and embedded PowerPC systems assume that all calls to
13426 variable argument functions are properly prototyped. Otherwise, the
13427 compiler must insert an instruction before every non prototyped call to
13428 set or clear bit 6 of the condition code register (@var{CR}) to
13429 indicate whether floating point values were passed in the floating point
13430 registers in case the function takes a variable arguments. With
13431 @option{-mprototype}, only calls to prototyped variable argument functions
13432 will set or clear the bit.
13436 On embedded PowerPC systems, assume that the startup module is called
13437 @file{sim-crt0.o} and that the standard C libraries are @file{libsim.a} and
13438 @file{libc.a}. This is the default for @samp{powerpc-*-eabisim}
13443 On embedded PowerPC systems, assume that the startup module is called
13444 @file{crt0.o} and the standard C libraries are @file{libmvme.a} and
13449 On embedded PowerPC systems, assume that the startup module is called
13450 @file{crt0.o} and the standard C libraries are @file{libads.a} and
13453 @item -myellowknife
13454 @opindex myellowknife
13455 On embedded PowerPC systems, assume that the startup module is called
13456 @file{crt0.o} and the standard C libraries are @file{libyk.a} and
13461 On System V.4 and embedded PowerPC systems, specify that you are
13462 compiling for a VxWorks system.
13466 Specify that you are compiling for the WindISS simulation environment.
13470 On embedded PowerPC systems, set the @var{PPC_EMB} bit in the ELF flags
13471 header to indicate that @samp{eabi} extended relocations are used.
13477 On System V.4 and embedded PowerPC systems do (do not) adhere to the
13478 Embedded Applications Binary Interface (eabi) which is a set of
13479 modifications to the System V.4 specifications. Selecting @option{-meabi}
13480 means that the stack is aligned to an 8 byte boundary, a function
13481 @code{__eabi} is called to from @code{main} to set up the eabi
13482 environment, and the @option{-msdata} option can use both @code{r2} and
13483 @code{r13} to point to two separate small data areas. Selecting
13484 @option{-mno-eabi} means that the stack is aligned to a 16 byte boundary,
13485 do not call an initialization function from @code{main}, and the
13486 @option{-msdata} option will only use @code{r13} to point to a single
13487 small data area. The @option{-meabi} option is on by default if you
13488 configured GCC using one of the @samp{powerpc*-*-eabi*} options.
13491 @opindex msdata=eabi
13492 On System V.4 and embedded PowerPC systems, put small initialized
13493 @code{const} global and static data in the @samp{.sdata2} section, which
13494 is pointed to by register @code{r2}. Put small initialized
13495 non-@code{const} global and static data in the @samp{.sdata} section,
13496 which is pointed to by register @code{r13}. Put small uninitialized
13497 global and static data in the @samp{.sbss} section, which is adjacent to
13498 the @samp{.sdata} section. The @option{-msdata=eabi} option is
13499 incompatible with the @option{-mrelocatable} option. The
13500 @option{-msdata=eabi} option also sets the @option{-memb} option.
13503 @opindex msdata=sysv
13504 On System V.4 and embedded PowerPC systems, put small global and static
13505 data in the @samp{.sdata} section, which is pointed to by register
13506 @code{r13}. Put small uninitialized global and static data in the
13507 @samp{.sbss} section, which is adjacent to the @samp{.sdata} section.
13508 The @option{-msdata=sysv} option is incompatible with the
13509 @option{-mrelocatable} option.
13511 @item -msdata=default
13513 @opindex msdata=default
13515 On System V.4 and embedded PowerPC systems, if @option{-meabi} is used,
13516 compile code the same as @option{-msdata=eabi}, otherwise compile code the
13517 same as @option{-msdata=sysv}.
13520 @opindex msdata-data
13521 On System V.4 and embedded PowerPC systems, put small global
13522 data in the @samp{.sdata} section. Put small uninitialized global
13523 data in the @samp{.sbss} section. Do not use register @code{r13}
13524 to address small data however. This is the default behavior unless
13525 other @option{-msdata} options are used.
13529 @opindex msdata=none
13531 On embedded PowerPC systems, put all initialized global and static data
13532 in the @samp{.data} section, and all uninitialized data in the
13533 @samp{.bss} section.
13537 @cindex smaller data references (PowerPC)
13538 @cindex .sdata/.sdata2 references (PowerPC)
13539 On embedded PowerPC systems, put global and static items less than or
13540 equal to @var{num} bytes into the small data or bss sections instead of
13541 the normal data or bss section. By default, @var{num} is 8. The
13542 @option{-G @var{num}} switch is also passed to the linker.
13543 All modules should be compiled with the same @option{-G @var{num}} value.
13546 @itemx -mno-regnames
13548 @opindex mno-regnames
13549 On System V.4 and embedded PowerPC systems do (do not) emit register
13550 names in the assembly language output using symbolic forms.
13553 @itemx -mno-longcall
13555 @opindex mno-longcall
13556 By default assume that all calls are far away so that a longer more
13557 expensive calling sequence is required. This is required for calls
13558 further than 32 megabytes (33,554,432 bytes) from the current location.
13559 A short call will be generated if the compiler knows
13560 the call cannot be that far away. This setting can be overridden by
13561 the @code{shortcall} function attribute, or by @code{#pragma
13564 Some linkers are capable of detecting out-of-range calls and generating
13565 glue code on the fly. On these systems, long calls are unnecessary and
13566 generate slower code. As of this writing, the AIX linker can do this,
13567 as can the GNU linker for PowerPC/64. It is planned to add this feature
13568 to the GNU linker for 32-bit PowerPC systems as well.
13570 On Darwin/PPC systems, @code{#pragma longcall} will generate ``jbsr
13571 callee, L42'', plus a ``branch island'' (glue code). The two target
13572 addresses represent the callee and the ``branch island''. The
13573 Darwin/PPC linker will prefer the first address and generate a ``bl
13574 callee'' if the PPC ``bl'' instruction will reach the callee directly;
13575 otherwise, the linker will generate ``bl L42'' to call the ``branch
13576 island''. The ``branch island'' is appended to the body of the
13577 calling function; it computes the full 32-bit address of the callee
13580 On Mach-O (Darwin) systems, this option directs the compiler emit to
13581 the glue for every direct call, and the Darwin linker decides whether
13582 to use or discard it.
13584 In the future, we may cause GCC to ignore all longcall specifications
13585 when the linker is known to generate glue.
13589 Adds support for multithreading with the @dfn{pthreads} library.
13590 This option sets flags for both the preprocessor and linker.
13594 @node S/390 and zSeries Options
13595 @subsection S/390 and zSeries Options
13596 @cindex S/390 and zSeries Options
13598 These are the @samp{-m} options defined for the S/390 and zSeries architecture.
13602 @itemx -msoft-float
13603 @opindex mhard-float
13604 @opindex msoft-float
13605 Use (do not use) the hardware floating-point instructions and registers
13606 for floating-point operations. When @option{-msoft-float} is specified,
13607 functions in @file{libgcc.a} will be used to perform floating-point
13608 operations. When @option{-mhard-float} is specified, the compiler
13609 generates IEEE floating-point instructions. This is the default.
13611 @item -mlong-double-64
13612 @itemx -mlong-double-128
13613 @opindex mlong-double-64
13614 @opindex mlong-double-128
13615 These switches control the size of @code{long double} type. A size
13616 of 64bit makes the @code{long double} type equivalent to the @code{double}
13617 type. This is the default.
13620 @itemx -mno-backchain
13621 @opindex mbackchain
13622 @opindex mno-backchain
13623 Store (do not store) the address of the caller's frame as backchain pointer
13624 into the callee's stack frame.
13625 A backchain may be needed to allow debugging using tools that do not understand
13626 DWARF-2 call frame information.
13627 When @option{-mno-packed-stack} is in effect, the backchain pointer is stored
13628 at the bottom of the stack frame; when @option{-mpacked-stack} is in effect,
13629 the backchain is placed into the topmost word of the 96/160 byte register
13632 In general, code compiled with @option{-mbackchain} is call-compatible with
13633 code compiled with @option{-mmo-backchain}; however, use of the backchain
13634 for debugging purposes usually requires that the whole binary is built with
13635 @option{-mbackchain}. Note that the combination of @option{-mbackchain},
13636 @option{-mpacked-stack} and @option{-mhard-float} is not supported. In order
13637 to build a linux kernel use @option{-msoft-float}.
13639 The default is to not maintain the backchain.
13641 @item -mpacked-stack
13642 @item -mno-packed-stack
13643 @opindex mpacked-stack
13644 @opindex mno-packed-stack
13645 Use (do not use) the packed stack layout. When @option{-mno-packed-stack} is
13646 specified, the compiler uses the all fields of the 96/160 byte register save
13647 area only for their default purpose; unused fields still take up stack space.
13648 When @option{-mpacked-stack} is specified, register save slots are densely
13649 packed at the top of the register save area; unused space is reused for other
13650 purposes, allowing for more efficient use of the available stack space.
13651 However, when @option{-mbackchain} is also in effect, the topmost word of
13652 the save area is always used to store the backchain, and the return address
13653 register is always saved two words below the backchain.
13655 As long as the stack frame backchain is not used, code generated with
13656 @option{-mpacked-stack} is call-compatible with code generated with
13657 @option{-mno-packed-stack}. Note that some non-FSF releases of GCC 2.95 for
13658 S/390 or zSeries generated code that uses the stack frame backchain at run
13659 time, not just for debugging purposes. Such code is not call-compatible
13660 with code compiled with @option{-mpacked-stack}. Also, note that the
13661 combination of @option{-mbackchain},
13662 @option{-mpacked-stack} and @option{-mhard-float} is not supported. In order
13663 to build a linux kernel use @option{-msoft-float}.
13665 The default is to not use the packed stack layout.
13668 @itemx -mno-small-exec
13669 @opindex msmall-exec
13670 @opindex mno-small-exec
13671 Generate (or do not generate) code using the @code{bras} instruction
13672 to do subroutine calls.
13673 This only works reliably if the total executable size does not
13674 exceed 64k. The default is to use the @code{basr} instruction instead,
13675 which does not have this limitation.
13681 When @option{-m31} is specified, generate code compliant to the
13682 GNU/Linux for S/390 ABI@. When @option{-m64} is specified, generate
13683 code compliant to the GNU/Linux for zSeries ABI@. This allows GCC in
13684 particular to generate 64-bit instructions. For the @samp{s390}
13685 targets, the default is @option{-m31}, while the @samp{s390x}
13686 targets default to @option{-m64}.
13692 When @option{-mzarch} is specified, generate code using the
13693 instructions available on z/Architecture.
13694 When @option{-mesa} is specified, generate code using the
13695 instructions available on ESA/390. Note that @option{-mesa} is
13696 not possible with @option{-m64}.
13697 When generating code compliant to the GNU/Linux for S/390 ABI,
13698 the default is @option{-mesa}. When generating code compliant
13699 to the GNU/Linux for zSeries ABI, the default is @option{-mzarch}.
13705 Generate (or do not generate) code using the @code{mvcle} instruction
13706 to perform block moves. When @option{-mno-mvcle} is specified,
13707 use a @code{mvc} loop instead. This is the default unless optimizing for
13714 Print (or do not print) additional debug information when compiling.
13715 The default is to not print debug information.
13717 @item -march=@var{cpu-type}
13719 Generate code that will run on @var{cpu-type}, which is the name of a system
13720 representing a certain processor type. Possible values for
13721 @var{cpu-type} are @samp{g5}, @samp{g6}, @samp{z900}, and @samp{z990}.
13722 When generating code using the instructions available on z/Architecture,
13723 the default is @option{-march=z900}. Otherwise, the default is
13724 @option{-march=g5}.
13726 @item -mtune=@var{cpu-type}
13728 Tune to @var{cpu-type} everything applicable about the generated code,
13729 except for the ABI and the set of available instructions.
13730 The list of @var{cpu-type} values is the same as for @option{-march}.
13731 The default is the value used for @option{-march}.
13734 @itemx -mno-tpf-trace
13735 @opindex mtpf-trace
13736 @opindex mno-tpf-trace
13737 Generate code that adds (does not add) in TPF OS specific branches to trace
13738 routines in the operating system. This option is off by default, even
13739 when compiling for the TPF OS@.
13742 @itemx -mno-fused-madd
13743 @opindex mfused-madd
13744 @opindex mno-fused-madd
13745 Generate code that uses (does not use) the floating point multiply and
13746 accumulate instructions. These instructions are generated by default if
13747 hardware floating point is used.
13749 @item -mwarn-framesize=@var{framesize}
13750 @opindex mwarn-framesize
13751 Emit a warning if the current function exceeds the given frame size. Because
13752 this is a compile time check it doesn't need to be a real problem when the program
13753 runs. It is intended to identify functions which most probably cause
13754 a stack overflow. It is useful to be used in an environment with limited stack
13755 size e.g.@: the linux kernel.
13757 @item -mwarn-dynamicstack
13758 @opindex mwarn-dynamicstack
13759 Emit a warning if the function calls alloca or uses dynamically
13760 sized arrays. This is generally a bad idea with a limited stack size.
13762 @item -mstack-guard=@var{stack-guard}
13763 @item -mstack-size=@var{stack-size}
13764 @opindex mstack-guard
13765 @opindex mstack-size
13766 If these options are provided the s390 back end emits additional instructions in
13767 the function prologue which trigger a trap if the stack size is @var{stack-guard}
13768 bytes above the @var{stack-size} (remember that the stack on s390 grows downward).
13769 If the @var{stack-guard} option is omitted the smallest power of 2 larger than
13770 the frame size of the compiled function is chosen.
13771 These options are intended to be used to help debugging stack overflow problems.
13772 The additionally emitted code causes only little overhead and hence can also be
13773 used in production like systems without greater performance degradation. The given
13774 values have to be exact powers of 2 and @var{stack-size} has to be greater than
13775 @var{stack-guard} without exceeding 64k.
13776 In order to be efficient the extra code makes the assumption that the stack starts
13777 at an address aligned to the value given by @var{stack-size}.
13778 The @var{stack-guard} option can only be used in conjunction with @var{stack-size}.
13781 @node Score Options
13782 @subsection Score Options
13783 @cindex Score Options
13785 These options are defined for Score implementations:
13790 Compile code for big endian mode. This is the default.
13794 Compile code for little endian mode.
13798 Disable generate bcnz instruction.
13802 Enable generate unaligned load and store instruction.
13806 Enable the use of multiply-accumulate instructions. Disabled by default.
13810 Specify the SCORE5 as the target architecture.
13814 Specify the SCORE5U of the target architecture.
13818 Specify the SCORE7 as the target architecture. This is the default.
13822 Specify the SCORE7D as the target architecture.
13826 @subsection SH Options
13828 These @samp{-m} options are defined for the SH implementations:
13833 Generate code for the SH1.
13837 Generate code for the SH2.
13840 Generate code for the SH2e.
13844 Generate code for the SH3.
13848 Generate code for the SH3e.
13852 Generate code for the SH4 without a floating-point unit.
13854 @item -m4-single-only
13855 @opindex m4-single-only
13856 Generate code for the SH4 with a floating-point unit that only
13857 supports single-precision arithmetic.
13861 Generate code for the SH4 assuming the floating-point unit is in
13862 single-precision mode by default.
13866 Generate code for the SH4.
13870 Generate code for the SH4al-dsp, or for a SH4a in such a way that the
13871 floating-point unit is not used.
13873 @item -m4a-single-only
13874 @opindex m4a-single-only
13875 Generate code for the SH4a, in such a way that no double-precision
13876 floating point operations are used.
13879 @opindex m4a-single
13880 Generate code for the SH4a assuming the floating-point unit is in
13881 single-precision mode by default.
13885 Generate code for the SH4a.
13889 Same as @option{-m4a-nofpu}, except that it implicitly passes
13890 @option{-dsp} to the assembler. GCC doesn't generate any DSP
13891 instructions at the moment.
13895 Compile code for the processor in big endian mode.
13899 Compile code for the processor in little endian mode.
13903 Align doubles at 64-bit boundaries. Note that this changes the calling
13904 conventions, and thus some functions from the standard C library will
13905 not work unless you recompile it first with @option{-mdalign}.
13909 Shorten some address references at link time, when possible; uses the
13910 linker option @option{-relax}.
13914 Use 32-bit offsets in @code{switch} tables. The default is to use
13919 Enable the use of the instruction @code{fmovd}.
13923 Comply with the calling conventions defined by Renesas.
13927 Comply with the calling conventions defined by Renesas.
13931 Comply with the calling conventions defined for GCC before the Renesas
13932 conventions were available. This option is the default for all
13933 targets of the SH toolchain except for @samp{sh-symbianelf}.
13936 @opindex mnomacsave
13937 Mark the @code{MAC} register as call-clobbered, even if
13938 @option{-mhitachi} is given.
13942 Increase IEEE-compliance of floating-point code.
13943 At the moment, this is equivalent to @option{-fno-finite-math-only}.
13944 When generating 16 bit SH opcodes, getting IEEE-conforming results for
13945 comparisons of NANs / infinities incurs extra overhead in every
13946 floating point comparison, therefore the default is set to
13947 @option{-ffinite-math-only}.
13949 @item -minline-ic_invalidate
13950 @opindex minline-ic_invalidate
13951 Inline code to invalidate instruction cache entries after setting up
13952 nested function trampolines.
13953 This option has no effect if -musermode is in effect and the selected
13954 code generation option (e.g. -m4) does not allow the use of the icbi
13956 If the selected code generation option does not allow the use of the icbi
13957 instruction, and -musermode is not in effect, the inlined code will
13958 manipulate the instruction cache address array directly with an associative
13959 write. This not only requires privileged mode, but it will also
13960 fail if the cache line had been mapped via the TLB and has become unmapped.
13964 Dump instruction size and location in the assembly code.
13967 @opindex mpadstruct
13968 This option is deprecated. It pads structures to multiple of 4 bytes,
13969 which is incompatible with the SH ABI@.
13973 Optimize for space instead of speed. Implied by @option{-Os}.
13976 @opindex mprefergot
13977 When generating position-independent code, emit function calls using
13978 the Global Offset Table instead of the Procedure Linkage Table.
13982 Don't generate privileged mode only code; implies -mno-inline-ic_invalidate
13983 if the inlined code would not work in user mode.
13984 This is the default when the target is @code{sh-*-linux*}.
13986 @item -multcost=@var{number}
13987 @opindex multcost=@var{number}
13988 Set the cost to assume for a multiply insn.
13990 @item -mdiv=@var{strategy}
13991 @opindex mdiv=@var{strategy}
13992 Set the division strategy to use for SHmedia code. @var{strategy} must be
13993 one of: call, call2, fp, inv, inv:minlat, inv20u, inv20l, inv:call,
13994 inv:call2, inv:fp .
13995 "fp" performs the operation in floating point. This has a very high latency,
13996 but needs only a few instructions, so it might be a good choice if
13997 your code has enough easily exploitable ILP to allow the compiler to
13998 schedule the floating point instructions together with other instructions.
13999 Division by zero causes a floating point exception.
14000 "inv" uses integer operations to calculate the inverse of the divisor,
14001 and then multiplies the dividend with the inverse. This strategy allows
14002 cse and hoisting of the inverse calculation. Division by zero calculates
14003 an unspecified result, but does not trap.
14004 "inv:minlat" is a variant of "inv" where if no cse / hoisting opportunities
14005 have been found, or if the entire operation has been hoisted to the same
14006 place, the last stages of the inverse calculation are intertwined with the
14007 final multiply to reduce the overall latency, at the expense of using a few
14008 more instructions, and thus offering fewer scheduling opportunities with
14010 "call" calls a library function that usually implements the inv:minlat
14012 This gives high code density for m5-*media-nofpu compilations.
14013 "call2" uses a different entry point of the same library function, where it
14014 assumes that a pointer to a lookup table has already been set up, which
14015 exposes the pointer load to cse / code hoisting optimizations.
14016 "inv:call", "inv:call2" and "inv:fp" all use the "inv" algorithm for initial
14017 code generation, but if the code stays unoptimized, revert to the "call",
14018 "call2", or "fp" strategies, respectively. Note that the
14019 potentially-trapping side effect of division by zero is carried by a
14020 separate instruction, so it is possible that all the integer instructions
14021 are hoisted out, but the marker for the side effect stays where it is.
14022 A recombination to fp operations or a call is not possible in that case.
14023 "inv20u" and "inv20l" are variants of the "inv:minlat" strategy. In the case
14024 that the inverse calculation was nor separated from the multiply, they speed
14025 up division where the dividend fits into 20 bits (plus sign where applicable),
14026 by inserting a test to skip a number of operations in this case; this test
14027 slows down the case of larger dividends. inv20u assumes the case of a such
14028 a small dividend to be unlikely, and inv20l assumes it to be likely.
14030 @item -mdivsi3_libfunc=@var{name}
14031 @opindex mdivsi3_libfunc=@var{name}
14032 Set the name of the library function used for 32 bit signed division to
14033 @var{name}. This only affect the name used in the call and inv:call
14034 division strategies, and the compiler will still expect the same
14035 sets of input/output/clobbered registers as if this option was not present.
14037 @item -madjust-unroll
14038 @opindex madjust-unroll
14039 Throttle unrolling to avoid thrashing target registers.
14040 This option only has an effect if the gcc code base supports the
14041 TARGET_ADJUST_UNROLL_MAX target hook.
14043 @item -mindexed-addressing
14044 @opindex mindexed-addressing
14045 Enable the use of the indexed addressing mode for SHmedia32/SHcompact.
14046 This is only safe if the hardware and/or OS implement 32 bit wrap-around
14047 semantics for the indexed addressing mode. The architecture allows the
14048 implementation of processors with 64 bit MMU, which the OS could use to
14049 get 32 bit addressing, but since no current hardware implementation supports
14050 this or any other way to make the indexed addressing mode safe to use in
14051 the 32 bit ABI, the default is -mno-indexed-addressing.
14053 @item -mgettrcost=@var{number}
14054 @opindex mgettrcost=@var{number}
14055 Set the cost assumed for the gettr instruction to @var{number}.
14056 The default is 2 if @option{-mpt-fixed} is in effect, 100 otherwise.
14060 Assume pt* instructions won't trap. This will generally generate better
14061 scheduled code, but is unsafe on current hardware. The current architecture
14062 definition says that ptabs and ptrel trap when the target anded with 3 is 3.
14063 This has the unintentional effect of making it unsafe to schedule ptabs /
14064 ptrel before a branch, or hoist it out of a loop. For example,
14065 __do_global_ctors, a part of libgcc that runs constructors at program
14066 startup, calls functions in a list which is delimited by @minus{}1. With the
14067 -mpt-fixed option, the ptabs will be done before testing against @minus{}1.
14068 That means that all the constructors will be run a bit quicker, but when
14069 the loop comes to the end of the list, the program crashes because ptabs
14070 loads @minus{}1 into a target register. Since this option is unsafe for any
14071 hardware implementing the current architecture specification, the default
14072 is -mno-pt-fixed. Unless the user specifies a specific cost with
14073 @option{-mgettrcost}, -mno-pt-fixed also implies @option{-mgettrcost=100};
14074 this deters register allocation using target registers for storing
14077 @item -minvalid-symbols
14078 @opindex minvalid-symbols
14079 Assume symbols might be invalid. Ordinary function symbols generated by
14080 the compiler will always be valid to load with movi/shori/ptabs or
14081 movi/shori/ptrel, but with assembler and/or linker tricks it is possible
14082 to generate symbols that will cause ptabs / ptrel to trap.
14083 This option is only meaningful when @option{-mno-pt-fixed} is in effect.
14084 It will then prevent cross-basic-block cse, hoisting and most scheduling
14085 of symbol loads. The default is @option{-mno-invalid-symbols}.
14088 @node SPARC Options
14089 @subsection SPARC Options
14090 @cindex SPARC options
14092 These @samp{-m} options are supported on the SPARC:
14095 @item -mno-app-regs
14097 @opindex mno-app-regs
14099 Specify @option{-mapp-regs} to generate output using the global registers
14100 2 through 4, which the SPARC SVR4 ABI reserves for applications. This
14103 To be fully SVR4 ABI compliant at the cost of some performance loss,
14104 specify @option{-mno-app-regs}. You should compile libraries and system
14105 software with this option.
14108 @itemx -mhard-float
14110 @opindex mhard-float
14111 Generate output containing floating point instructions. This is the
14115 @itemx -msoft-float
14117 @opindex msoft-float
14118 Generate output containing library calls for floating point.
14119 @strong{Warning:} the requisite libraries are not available for all SPARC
14120 targets. Normally the facilities of the machine's usual C compiler are
14121 used, but this cannot be done directly in cross-compilation. You must make
14122 your own arrangements to provide suitable library functions for
14123 cross-compilation. The embedded targets @samp{sparc-*-aout} and
14124 @samp{sparclite-*-*} do provide software floating point support.
14126 @option{-msoft-float} changes the calling convention in the output file;
14127 therefore, it is only useful if you compile @emph{all} of a program with
14128 this option. In particular, you need to compile @file{libgcc.a}, the
14129 library that comes with GCC, with @option{-msoft-float} in order for
14132 @item -mhard-quad-float
14133 @opindex mhard-quad-float
14134 Generate output containing quad-word (long double) floating point
14137 @item -msoft-quad-float
14138 @opindex msoft-quad-float
14139 Generate output containing library calls for quad-word (long double)
14140 floating point instructions. The functions called are those specified
14141 in the SPARC ABI@. This is the default.
14143 As of this writing, there are no SPARC implementations that have hardware
14144 support for the quad-word floating point instructions. They all invoke
14145 a trap handler for one of these instructions, and then the trap handler
14146 emulates the effect of the instruction. Because of the trap handler overhead,
14147 this is much slower than calling the ABI library routines. Thus the
14148 @option{-msoft-quad-float} option is the default.
14150 @item -mno-unaligned-doubles
14151 @itemx -munaligned-doubles
14152 @opindex mno-unaligned-doubles
14153 @opindex munaligned-doubles
14154 Assume that doubles have 8 byte alignment. This is the default.
14156 With @option{-munaligned-doubles}, GCC assumes that doubles have 8 byte
14157 alignment only if they are contained in another type, or if they have an
14158 absolute address. Otherwise, it assumes they have 4 byte alignment.
14159 Specifying this option avoids some rare compatibility problems with code
14160 generated by other compilers. It is not the default because it results
14161 in a performance loss, especially for floating point code.
14163 @item -mno-faster-structs
14164 @itemx -mfaster-structs
14165 @opindex mno-faster-structs
14166 @opindex mfaster-structs
14167 With @option{-mfaster-structs}, the compiler assumes that structures
14168 should have 8 byte alignment. This enables the use of pairs of
14169 @code{ldd} and @code{std} instructions for copies in structure
14170 assignment, in place of twice as many @code{ld} and @code{st} pairs.
14171 However, the use of this changed alignment directly violates the SPARC
14172 ABI@. Thus, it's intended only for use on targets where the developer
14173 acknowledges that their resulting code will not be directly in line with
14174 the rules of the ABI@.
14176 @item -mimpure-text
14177 @opindex mimpure-text
14178 @option{-mimpure-text}, used in addition to @option{-shared}, tells
14179 the compiler to not pass @option{-z text} to the linker when linking a
14180 shared object. Using this option, you can link position-dependent
14181 code into a shared object.
14183 @option{-mimpure-text} suppresses the ``relocations remain against
14184 allocatable but non-writable sections'' linker error message.
14185 However, the necessary relocations will trigger copy-on-write, and the
14186 shared object is not actually shared across processes. Instead of
14187 using @option{-mimpure-text}, you should compile all source code with
14188 @option{-fpic} or @option{-fPIC}.
14190 This option is only available on SunOS and Solaris.
14192 @item -mcpu=@var{cpu_type}
14194 Set the instruction set, register set, and instruction scheduling parameters
14195 for machine type @var{cpu_type}. Supported values for @var{cpu_type} are
14196 @samp{v7}, @samp{cypress}, @samp{v8}, @samp{supersparc}, @samp{sparclite},
14197 @samp{f930}, @samp{f934}, @samp{hypersparc}, @samp{sparclite86x},
14198 @samp{sparclet}, @samp{tsc701}, @samp{v9}, @samp{ultrasparc},
14199 @samp{ultrasparc3}, @samp{niagara} and @samp{niagara2}.
14201 Default instruction scheduling parameters are used for values that select
14202 an architecture and not an implementation. These are @samp{v7}, @samp{v8},
14203 @samp{sparclite}, @samp{sparclet}, @samp{v9}.
14205 Here is a list of each supported architecture and their supported
14210 v8: supersparc, hypersparc
14211 sparclite: f930, f934, sparclite86x
14213 v9: ultrasparc, ultrasparc3, niagara, niagara2
14216 By default (unless configured otherwise), GCC generates code for the V7
14217 variant of the SPARC architecture. With @option{-mcpu=cypress}, the compiler
14218 additionally optimizes it for the Cypress CY7C602 chip, as used in the
14219 SPARCStation/SPARCServer 3xx series. This is also appropriate for the older
14220 SPARCStation 1, 2, IPX etc.
14222 With @option{-mcpu=v8}, GCC generates code for the V8 variant of the SPARC
14223 architecture. The only difference from V7 code is that the compiler emits
14224 the integer multiply and integer divide instructions which exist in SPARC-V8
14225 but not in SPARC-V7. With @option{-mcpu=supersparc}, the compiler additionally
14226 optimizes it for the SuperSPARC chip, as used in the SPARCStation 10, 1000 and
14229 With @option{-mcpu=sparclite}, GCC generates code for the SPARClite variant of
14230 the SPARC architecture. This adds the integer multiply, integer divide step
14231 and scan (@code{ffs}) instructions which exist in SPARClite but not in SPARC-V7.
14232 With @option{-mcpu=f930}, the compiler additionally optimizes it for the
14233 Fujitsu MB86930 chip, which is the original SPARClite, with no FPU@. With
14234 @option{-mcpu=f934}, the compiler additionally optimizes it for the Fujitsu
14235 MB86934 chip, which is the more recent SPARClite with FPU@.
14237 With @option{-mcpu=sparclet}, GCC generates code for the SPARClet variant of
14238 the SPARC architecture. This adds the integer multiply, multiply/accumulate,
14239 integer divide step and scan (@code{ffs}) instructions which exist in SPARClet
14240 but not in SPARC-V7. With @option{-mcpu=tsc701}, the compiler additionally
14241 optimizes it for the TEMIC SPARClet chip.
14243 With @option{-mcpu=v9}, GCC generates code for the V9 variant of the SPARC
14244 architecture. This adds 64-bit integer and floating-point move instructions,
14245 3 additional floating-point condition code registers and conditional move
14246 instructions. With @option{-mcpu=ultrasparc}, the compiler additionally
14247 optimizes it for the Sun UltraSPARC I/II/IIi chips. With
14248 @option{-mcpu=ultrasparc3}, the compiler additionally optimizes it for the
14249 Sun UltraSPARC III/III+/IIIi/IIIi+/IV/IV+ chips. With
14250 @option{-mcpu=niagara}, the compiler additionally optimizes it for
14251 Sun UltraSPARC T1 chips. With @option{-mcpu=niagara2}, the compiler
14252 additionally optimizes it for Sun UltraSPARC T2 chips.
14254 @item -mtune=@var{cpu_type}
14256 Set the instruction scheduling parameters for machine type
14257 @var{cpu_type}, but do not set the instruction set or register set that the
14258 option @option{-mcpu=@var{cpu_type}} would.
14260 The same values for @option{-mcpu=@var{cpu_type}} can be used for
14261 @option{-mtune=@var{cpu_type}}, but the only useful values are those
14262 that select a particular cpu implementation. Those are @samp{cypress},
14263 @samp{supersparc}, @samp{hypersparc}, @samp{f930}, @samp{f934},
14264 @samp{sparclite86x}, @samp{tsc701}, @samp{ultrasparc},
14265 @samp{ultrasparc3}, @samp{niagara}, and @samp{niagara2}.
14270 @opindex mno-v8plus
14271 With @option{-mv8plus}, GCC generates code for the SPARC-V8+ ABI@. The
14272 difference from the V8 ABI is that the global and out registers are
14273 considered 64-bit wide. This is enabled by default on Solaris in 32-bit
14274 mode for all SPARC-V9 processors.
14280 With @option{-mvis}, GCC generates code that takes advantage of the UltraSPARC
14281 Visual Instruction Set extensions. The default is @option{-mno-vis}.
14284 These @samp{-m} options are supported in addition to the above
14285 on SPARC-V9 processors in 64-bit environments:
14288 @item -mlittle-endian
14289 @opindex mlittle-endian
14290 Generate code for a processor running in little-endian mode. It is only
14291 available for a few configurations and most notably not on Solaris and Linux.
14297 Generate code for a 32-bit or 64-bit environment.
14298 The 32-bit environment sets int, long and pointer to 32 bits.
14299 The 64-bit environment sets int to 32 bits and long and pointer
14302 @item -mcmodel=medlow
14303 @opindex mcmodel=medlow
14304 Generate code for the Medium/Low code model: 64-bit addresses, programs
14305 must be linked in the low 32 bits of memory. Programs can be statically
14306 or dynamically linked.
14308 @item -mcmodel=medmid
14309 @opindex mcmodel=medmid
14310 Generate code for the Medium/Middle code model: 64-bit addresses, programs
14311 must be linked in the low 44 bits of memory, the text and data segments must
14312 be less than 2GB in size and the data segment must be located within 2GB of
14315 @item -mcmodel=medany
14316 @opindex mcmodel=medany
14317 Generate code for the Medium/Anywhere code model: 64-bit addresses, programs
14318 may be linked anywhere in memory, the text and data segments must be less
14319 than 2GB in size and the data segment must be located within 2GB of the
14322 @item -mcmodel=embmedany
14323 @opindex mcmodel=embmedany
14324 Generate code for the Medium/Anywhere code model for embedded systems:
14325 64-bit addresses, the text and data segments must be less than 2GB in
14326 size, both starting anywhere in memory (determined at link time). The
14327 global register %g4 points to the base of the data segment. Programs
14328 are statically linked and PIC is not supported.
14331 @itemx -mno-stack-bias
14332 @opindex mstack-bias
14333 @opindex mno-stack-bias
14334 With @option{-mstack-bias}, GCC assumes that the stack pointer, and
14335 frame pointer if present, are offset by @minus{}2047 which must be added back
14336 when making stack frame references. This is the default in 64-bit mode.
14337 Otherwise, assume no such offset is present.
14340 These switches are supported in addition to the above on Solaris:
14345 Add support for multithreading using the Solaris threads library. This
14346 option sets flags for both the preprocessor and linker. This option does
14347 not affect the thread safety of object code produced by the compiler or
14348 that of libraries supplied with it.
14352 Add support for multithreading using the POSIX threads library. This
14353 option sets flags for both the preprocessor and linker. This option does
14354 not affect the thread safety of object code produced by the compiler or
14355 that of libraries supplied with it.
14359 This is a synonym for @option{-pthreads}.
14363 @subsection SPU Options
14364 @cindex SPU options
14366 These @samp{-m} options are supported on the SPU:
14370 @itemx -merror-reloc
14371 @opindex mwarn-reloc
14372 @opindex merror-reloc
14374 The loader for SPU does not handle dynamic relocations. By default, GCC
14375 will give an error when it generates code that requires a dynamic
14376 relocation. @option{-mno-error-reloc} disables the error,
14377 @option{-mwarn-reloc} will generate a warning instead.
14380 @itemx -munsafe-dma
14382 @opindex munsafe-dma
14384 Instructions which initiate or test completion of DMA must not be
14385 reordered with respect to loads and stores of the memory which is being
14386 accessed. Users typically address this problem using the volatile
14387 keyword, but that can lead to inefficient code in places where the
14388 memory is known to not change. Rather than mark the memory as volatile
14389 we treat the DMA instructions as potentially effecting all memory. With
14390 @option{-munsafe-dma} users must use the volatile keyword to protect
14393 @item -mbranch-hints
14394 @opindex mbranch-hints
14396 By default, GCC will generate a branch hint instruction to avoid
14397 pipeline stalls for always taken or probably taken branches. A hint
14398 will not be generated closer than 8 instructions away from its branch.
14399 There is little reason to disable them, except for debugging purposes,
14400 or to make an object a little bit smaller.
14404 @opindex msmall-mem
14405 @opindex mlarge-mem
14407 By default, GCC generates code assuming that addresses are never larger
14408 than 18 bits. With @option{-mlarge-mem} code is generated that assumes
14409 a full 32 bit address.
14414 By default, GCC links against startup code that assumes the SPU-style
14415 main function interface (which has an unconventional parameter list).
14416 With @option{-mstdmain}, GCC will link your program against startup
14417 code that assumes a C99-style interface to @code{main}, including a
14418 local copy of @code{argv} strings.
14420 @item -mfixed-range=@var{register-range}
14421 @opindex mfixed-range
14422 Generate code treating the given register range as fixed registers.
14423 A fixed register is one that the register allocator can not use. This is
14424 useful when compiling kernel code. A register range is specified as
14425 two registers separated by a dash. Multiple register ranges can be
14426 specified separated by a comma.
14430 @node System V Options
14431 @subsection Options for System V
14433 These additional options are available on System V Release 4 for
14434 compatibility with other compilers on those systems:
14439 Create a shared object.
14440 It is recommended that @option{-symbolic} or @option{-shared} be used instead.
14444 Identify the versions of each tool used by the compiler, in a
14445 @code{.ident} assembler directive in the output.
14449 Refrain from adding @code{.ident} directives to the output file (this is
14452 @item -YP,@var{dirs}
14454 Search the directories @var{dirs}, and no others, for libraries
14455 specified with @option{-l}.
14457 @item -Ym,@var{dir}
14459 Look in the directory @var{dir} to find the M4 preprocessor.
14460 The assembler uses this option.
14461 @c This is supposed to go with a -Yd for predefined M4 macro files, but
14462 @c the generic assembler that comes with Solaris takes just -Ym.
14466 @subsection V850 Options
14467 @cindex V850 Options
14469 These @samp{-m} options are defined for V850 implementations:
14473 @itemx -mno-long-calls
14474 @opindex mlong-calls
14475 @opindex mno-long-calls
14476 Treat all calls as being far away (near). If calls are assumed to be
14477 far away, the compiler will always load the functions address up into a
14478 register, and call indirect through the pointer.
14484 Do not optimize (do optimize) basic blocks that use the same index
14485 pointer 4 or more times to copy pointer into the @code{ep} register, and
14486 use the shorter @code{sld} and @code{sst} instructions. The @option{-mep}
14487 option is on by default if you optimize.
14489 @item -mno-prolog-function
14490 @itemx -mprolog-function
14491 @opindex mno-prolog-function
14492 @opindex mprolog-function
14493 Do not use (do use) external functions to save and restore registers
14494 at the prologue and epilogue of a function. The external functions
14495 are slower, but use less code space if more than one function saves
14496 the same number of registers. The @option{-mprolog-function} option
14497 is on by default if you optimize.
14501 Try to make the code as small as possible. At present, this just turns
14502 on the @option{-mep} and @option{-mprolog-function} options.
14504 @item -mtda=@var{n}
14506 Put static or global variables whose size is @var{n} bytes or less into
14507 the tiny data area that register @code{ep} points to. The tiny data
14508 area can hold up to 256 bytes in total (128 bytes for byte references).
14510 @item -msda=@var{n}
14512 Put static or global variables whose size is @var{n} bytes or less into
14513 the small data area that register @code{gp} points to. The small data
14514 area can hold up to 64 kilobytes.
14516 @item -mzda=@var{n}
14518 Put static or global variables whose size is @var{n} bytes or less into
14519 the first 32 kilobytes of memory.
14523 Specify that the target processor is the V850.
14526 @opindex mbig-switch
14527 Generate code suitable for big switch tables. Use this option only if
14528 the assembler/linker complain about out of range branches within a switch
14533 This option will cause r2 and r5 to be used in the code generated by
14534 the compiler. This setting is the default.
14536 @item -mno-app-regs
14537 @opindex mno-app-regs
14538 This option will cause r2 and r5 to be treated as fixed registers.
14542 Specify that the target processor is the V850E1. The preprocessor
14543 constants @samp{__v850e1__} and @samp{__v850e__} will be defined if
14544 this option is used.
14548 Specify that the target processor is the V850E@. The preprocessor
14549 constant @samp{__v850e__} will be defined if this option is used.
14551 If neither @option{-mv850} nor @option{-mv850e} nor @option{-mv850e1}
14552 are defined then a default target processor will be chosen and the
14553 relevant @samp{__v850*__} preprocessor constant will be defined.
14555 The preprocessor constants @samp{__v850} and @samp{__v851__} are always
14556 defined, regardless of which processor variant is the target.
14558 @item -mdisable-callt
14559 @opindex mdisable-callt
14560 This option will suppress generation of the CALLT instruction for the
14561 v850e and v850e1 flavors of the v850 architecture. The default is
14562 @option{-mno-disable-callt} which allows the CALLT instruction to be used.
14567 @subsection VAX Options
14568 @cindex VAX options
14570 These @samp{-m} options are defined for the VAX:
14575 Do not output certain jump instructions (@code{aobleq} and so on)
14576 that the Unix assembler for the VAX cannot handle across long
14581 Do output those jump instructions, on the assumption that you
14582 will assemble with the GNU assembler.
14586 Output code for g-format floating point numbers instead of d-format.
14589 @node VxWorks Options
14590 @subsection VxWorks Options
14591 @cindex VxWorks Options
14593 The options in this section are defined for all VxWorks targets.
14594 Options specific to the target hardware are listed with the other
14595 options for that target.
14600 GCC can generate code for both VxWorks kernels and real time processes
14601 (RTPs). This option switches from the former to the latter. It also
14602 defines the preprocessor macro @code{__RTP__}.
14605 @opindex non-static
14606 Link an RTP executable against shared libraries rather than static
14607 libraries. The options @option{-static} and @option{-shared} can
14608 also be used for RTPs (@pxref{Link Options}); @option{-static}
14615 These options are passed down to the linker. They are defined for
14616 compatibility with Diab.
14619 @opindex Xbind-lazy
14620 Enable lazy binding of function calls. This option is equivalent to
14621 @option{-Wl,-z,now} and is defined for compatibility with Diab.
14625 Disable lazy binding of function calls. This option is the default and
14626 is defined for compatibility with Diab.
14629 @node x86-64 Options
14630 @subsection x86-64 Options
14631 @cindex x86-64 options
14633 These are listed under @xref{i386 and x86-64 Options}.
14635 @node Xstormy16 Options
14636 @subsection Xstormy16 Options
14637 @cindex Xstormy16 Options
14639 These options are defined for Xstormy16:
14644 Choose startup files and linker script suitable for the simulator.
14647 @node Xtensa Options
14648 @subsection Xtensa Options
14649 @cindex Xtensa Options
14651 These options are supported for Xtensa targets:
14655 @itemx -mno-const16
14657 @opindex mno-const16
14658 Enable or disable use of @code{CONST16} instructions for loading
14659 constant values. The @code{CONST16} instruction is currently not a
14660 standard option from Tensilica. When enabled, @code{CONST16}
14661 instructions are always used in place of the standard @code{L32R}
14662 instructions. The use of @code{CONST16} is enabled by default only if
14663 the @code{L32R} instruction is not available.
14666 @itemx -mno-fused-madd
14667 @opindex mfused-madd
14668 @opindex mno-fused-madd
14669 Enable or disable use of fused multiply/add and multiply/subtract
14670 instructions in the floating-point option. This has no effect if the
14671 floating-point option is not also enabled. Disabling fused multiply/add
14672 and multiply/subtract instructions forces the compiler to use separate
14673 instructions for the multiply and add/subtract operations. This may be
14674 desirable in some cases where strict IEEE 754-compliant results are
14675 required: the fused multiply add/subtract instructions do not round the
14676 intermediate result, thereby producing results with @emph{more} bits of
14677 precision than specified by the IEEE standard. Disabling fused multiply
14678 add/subtract instructions also ensures that the program output is not
14679 sensitive to the compiler's ability to combine multiply and add/subtract
14682 @item -mtext-section-literals
14683 @itemx -mno-text-section-literals
14684 @opindex mtext-section-literals
14685 @opindex mno-text-section-literals
14686 Control the treatment of literal pools. The default is
14687 @option{-mno-text-section-literals}, which places literals in a separate
14688 section in the output file. This allows the literal pool to be placed
14689 in a data RAM/ROM, and it also allows the linker to combine literal
14690 pools from separate object files to remove redundant literals and
14691 improve code size. With @option{-mtext-section-literals}, the literals
14692 are interspersed in the text section in order to keep them as close as
14693 possible to their references. This may be necessary for large assembly
14696 @item -mtarget-align
14697 @itemx -mno-target-align
14698 @opindex mtarget-align
14699 @opindex mno-target-align
14700 When this option is enabled, GCC instructs the assembler to
14701 automatically align instructions to reduce branch penalties at the
14702 expense of some code density. The assembler attempts to widen density
14703 instructions to align branch targets and the instructions following call
14704 instructions. If there are not enough preceding safe density
14705 instructions to align a target, no widening will be performed. The
14706 default is @option{-mtarget-align}. These options do not affect the
14707 treatment of auto-aligned instructions like @code{LOOP}, which the
14708 assembler will always align, either by widening density instructions or
14709 by inserting no-op instructions.
14712 @itemx -mno-longcalls
14713 @opindex mlongcalls
14714 @opindex mno-longcalls
14715 When this option is enabled, GCC instructs the assembler to translate
14716 direct calls to indirect calls unless it can determine that the target
14717 of a direct call is in the range allowed by the call instruction. This
14718 translation typically occurs for calls to functions in other source
14719 files. Specifically, the assembler translates a direct @code{CALL}
14720 instruction into an @code{L32R} followed by a @code{CALLX} instruction.
14721 The default is @option{-mno-longcalls}. This option should be used in
14722 programs where the call target can potentially be out of range. This
14723 option is implemented in the assembler, not the compiler, so the
14724 assembly code generated by GCC will still show direct call
14725 instructions---look at the disassembled object code to see the actual
14726 instructions. Note that the assembler will use an indirect call for
14727 every cross-file call, not just those that really will be out of range.
14730 @node zSeries Options
14731 @subsection zSeries Options
14732 @cindex zSeries options
14734 These are listed under @xref{S/390 and zSeries Options}.
14736 @node Code Gen Options
14737 @section Options for Code Generation Conventions
14738 @cindex code generation conventions
14739 @cindex options, code generation
14740 @cindex run-time options
14742 These machine-independent options control the interface conventions
14743 used in code generation.
14745 Most of them have both positive and negative forms; the negative form
14746 of @option{-ffoo} would be @option{-fno-foo}. In the table below, only
14747 one of the forms is listed---the one which is not the default. You
14748 can figure out the other form by either removing @samp{no-} or adding
14752 @item -fbounds-check
14753 @opindex fbounds-check
14754 For front-ends that support it, generate additional code to check that
14755 indices used to access arrays are within the declared range. This is
14756 currently only supported by the Java and Fortran front-ends, where
14757 this option defaults to true and false respectively.
14761 This option generates traps for signed overflow on addition, subtraction,
14762 multiplication operations.
14766 This option instructs the compiler to assume that signed arithmetic
14767 overflow of addition, subtraction and multiplication wraps around
14768 using twos-complement representation. This flag enables some optimizations
14769 and disables others. This option is enabled by default for the Java
14770 front-end, as required by the Java language specification.
14773 @opindex fexceptions
14774 Enable exception handling. Generates extra code needed to propagate
14775 exceptions. For some targets, this implies GCC will generate frame
14776 unwind information for all functions, which can produce significant data
14777 size overhead, although it does not affect execution. If you do not
14778 specify this option, GCC will enable it by default for languages like
14779 C++ which normally require exception handling, and disable it for
14780 languages like C that do not normally require it. However, you may need
14781 to enable this option when compiling C code that needs to interoperate
14782 properly with exception handlers written in C++. You may also wish to
14783 disable this option if you are compiling older C++ programs that don't
14784 use exception handling.
14786 @item -fnon-call-exceptions
14787 @opindex fnon-call-exceptions
14788 Generate code that allows trapping instructions to throw exceptions.
14789 Note that this requires platform-specific runtime support that does
14790 not exist everywhere. Moreover, it only allows @emph{trapping}
14791 instructions to throw exceptions, i.e.@: memory references or floating
14792 point instructions. It does not allow exceptions to be thrown from
14793 arbitrary signal handlers such as @code{SIGALRM}.
14795 @item -funwind-tables
14796 @opindex funwind-tables
14797 Similar to @option{-fexceptions}, except that it will just generate any needed
14798 static data, but will not affect the generated code in any other way.
14799 You will normally not enable this option; instead, a language processor
14800 that needs this handling would enable it on your behalf.
14802 @item -fasynchronous-unwind-tables
14803 @opindex fasynchronous-unwind-tables
14804 Generate unwind table in dwarf2 format, if supported by target machine. The
14805 table is exact at each instruction boundary, so it can be used for stack
14806 unwinding from asynchronous events (such as debugger or garbage collector).
14808 @item -fpcc-struct-return
14809 @opindex fpcc-struct-return
14810 Return ``short'' @code{struct} and @code{union} values in memory like
14811 longer ones, rather than in registers. This convention is less
14812 efficient, but it has the advantage of allowing intercallability between
14813 GCC-compiled files and files compiled with other compilers, particularly
14814 the Portable C Compiler (pcc).
14816 The precise convention for returning structures in memory depends
14817 on the target configuration macros.
14819 Short structures and unions are those whose size and alignment match
14820 that of some integer type.
14822 @strong{Warning:} code compiled with the @option{-fpcc-struct-return}
14823 switch is not binary compatible with code compiled with the
14824 @option{-freg-struct-return} switch.
14825 Use it to conform to a non-default application binary interface.
14827 @item -freg-struct-return
14828 @opindex freg-struct-return
14829 Return @code{struct} and @code{union} values in registers when possible.
14830 This is more efficient for small structures than
14831 @option{-fpcc-struct-return}.
14833 If you specify neither @option{-fpcc-struct-return} nor
14834 @option{-freg-struct-return}, GCC defaults to whichever convention is
14835 standard for the target. If there is no standard convention, GCC
14836 defaults to @option{-fpcc-struct-return}, except on targets where GCC is
14837 the principal compiler. In those cases, we can choose the standard, and
14838 we chose the more efficient register return alternative.
14840 @strong{Warning:} code compiled with the @option{-freg-struct-return}
14841 switch is not binary compatible with code compiled with the
14842 @option{-fpcc-struct-return} switch.
14843 Use it to conform to a non-default application binary interface.
14845 @item -fshort-enums
14846 @opindex fshort-enums
14847 Allocate to an @code{enum} type only as many bytes as it needs for the
14848 declared range of possible values. Specifically, the @code{enum} type
14849 will be equivalent to the smallest integer type which has enough room.
14851 @strong{Warning:} the @option{-fshort-enums} switch causes GCC to generate
14852 code that is not binary compatible with code generated without that switch.
14853 Use it to conform to a non-default application binary interface.
14855 @item -fshort-double
14856 @opindex fshort-double
14857 Use the same size for @code{double} as for @code{float}.
14859 @strong{Warning:} the @option{-fshort-double} switch causes GCC to generate
14860 code that is not binary compatible with code generated without that switch.
14861 Use it to conform to a non-default application binary interface.
14863 @item -fshort-wchar
14864 @opindex fshort-wchar
14865 Override the underlying type for @samp{wchar_t} to be @samp{short
14866 unsigned int} instead of the default for the target. This option is
14867 useful for building programs to run under WINE@.
14869 @strong{Warning:} the @option{-fshort-wchar} switch causes GCC to generate
14870 code that is not binary compatible with code generated without that switch.
14871 Use it to conform to a non-default application binary interface.
14874 @opindex fno-common
14875 In C, allocate even uninitialized global variables in the data section of the
14876 object file, rather than generating them as common blocks. This has the
14877 effect that if the same variable is declared (without @code{extern}) in
14878 two different compilations, you will get an error when you link them.
14879 The only reason this might be useful is if you wish to verify that the
14880 program will work on other systems which always work this way.
14884 Ignore the @samp{#ident} directive.
14886 @item -finhibit-size-directive
14887 @opindex finhibit-size-directive
14888 Don't output a @code{.size} assembler directive, or anything else that
14889 would cause trouble if the function is split in the middle, and the
14890 two halves are placed at locations far apart in memory. This option is
14891 used when compiling @file{crtstuff.c}; you should not need to use it
14894 @item -fverbose-asm
14895 @opindex fverbose-asm
14896 Put extra commentary information in the generated assembly code to
14897 make it more readable. This option is generally only of use to those
14898 who actually need to read the generated assembly code (perhaps while
14899 debugging the compiler itself).
14901 @option{-fno-verbose-asm}, the default, causes the
14902 extra information to be omitted and is useful when comparing two assembler
14905 @item -frecord-gcc-switches
14906 @opindex frecord-gcc-switches
14907 This switch causes the command line that was used to invoke the
14908 compiler to be recorded into the object file that is being created.
14909 This switch is only implemented on some targets and the exact format
14910 of the recording is target and binary file format dependent, but it
14911 usually takes the form of a section containing ASCII text. This
14912 switch is related to the @option{-fverbose-asm} switch, but that
14913 switch only records information in the assembler output file as
14914 comments, so it never reaches the object file.
14918 @cindex global offset table
14920 Generate position-independent code (PIC) suitable for use in a shared
14921 library, if supported for the target machine. Such code accesses all
14922 constant addresses through a global offset table (GOT)@. The dynamic
14923 loader resolves the GOT entries when the program starts (the dynamic
14924 loader is not part of GCC; it is part of the operating system). If
14925 the GOT size for the linked executable exceeds a machine-specific
14926 maximum size, you get an error message from the linker indicating that
14927 @option{-fpic} does not work; in that case, recompile with @option{-fPIC}
14928 instead. (These maximums are 8k on the SPARC and 32k
14929 on the m68k and RS/6000. The 386 has no such limit.)
14931 Position-independent code requires special support, and therefore works
14932 only on certain machines. For the 386, GCC supports PIC for System V
14933 but not for the Sun 386i. Code generated for the IBM RS/6000 is always
14934 position-independent.
14936 When this flag is set, the macros @code{__pic__} and @code{__PIC__}
14941 If supported for the target machine, emit position-independent code,
14942 suitable for dynamic linking and avoiding any limit on the size of the
14943 global offset table. This option makes a difference on the m68k,
14944 PowerPC and SPARC@.
14946 Position-independent code requires special support, and therefore works
14947 only on certain machines.
14949 When this flag is set, the macros @code{__pic__} and @code{__PIC__}
14956 These options are similar to @option{-fpic} and @option{-fPIC}, but
14957 generated position independent code can be only linked into executables.
14958 Usually these options are used when @option{-pie} GCC option will be
14959 used during linking.
14961 @option{-fpie} and @option{-fPIE} both define the macros
14962 @code{__pie__} and @code{__PIE__}. The macros have the value 1
14963 for @option{-fpie} and 2 for @option{-fPIE}.
14965 @item -fno-jump-tables
14966 @opindex fno-jump-tables
14967 Do not use jump tables for switch statements even where it would be
14968 more efficient than other code generation strategies. This option is
14969 of use in conjunction with @option{-fpic} or @option{-fPIC} for
14970 building code which forms part of a dynamic linker and cannot
14971 reference the address of a jump table. On some targets, jump tables
14972 do not require a GOT and this option is not needed.
14974 @item -ffixed-@var{reg}
14976 Treat the register named @var{reg} as a fixed register; generated code
14977 should never refer to it (except perhaps as a stack pointer, frame
14978 pointer or in some other fixed role).
14980 @var{reg} must be the name of a register. The register names accepted
14981 are machine-specific and are defined in the @code{REGISTER_NAMES}
14982 macro in the machine description macro file.
14984 This flag does not have a negative form, because it specifies a
14987 @item -fcall-used-@var{reg}
14988 @opindex fcall-used
14989 Treat the register named @var{reg} as an allocable register that is
14990 clobbered by function calls. It may be allocated for temporaries or
14991 variables that do not live across a call. Functions compiled this way
14992 will not save and restore the register @var{reg}.
14994 It is an error to used this flag with the frame pointer or stack pointer.
14995 Use of this flag for other registers that have fixed pervasive roles in
14996 the machine's execution model will produce disastrous results.
14998 This flag does not have a negative form, because it specifies a
15001 @item -fcall-saved-@var{reg}
15002 @opindex fcall-saved
15003 Treat the register named @var{reg} as an allocable register saved by
15004 functions. It may be allocated even for temporaries or variables that
15005 live across a call. Functions compiled this way will save and restore
15006 the register @var{reg} if they use it.
15008 It is an error to used this flag with the frame pointer or stack pointer.
15009 Use of this flag for other registers that have fixed pervasive roles in
15010 the machine's execution model will produce disastrous results.
15012 A different sort of disaster will result from the use of this flag for
15013 a register in which function values may be returned.
15015 This flag does not have a negative form, because it specifies a
15018 @item -fpack-struct[=@var{n}]
15019 @opindex fpack-struct
15020 Without a value specified, pack all structure members together without
15021 holes. When a value is specified (which must be a small power of two), pack
15022 structure members according to this value, representing the maximum
15023 alignment (that is, objects with default alignment requirements larger than
15024 this will be output potentially unaligned at the next fitting location.
15026 @strong{Warning:} the @option{-fpack-struct} switch causes GCC to generate
15027 code that is not binary compatible with code generated without that switch.
15028 Additionally, it makes the code suboptimal.
15029 Use it to conform to a non-default application binary interface.
15031 @item -finstrument-functions
15032 @opindex finstrument-functions
15033 Generate instrumentation calls for entry and exit to functions. Just
15034 after function entry and just before function exit, the following
15035 profiling functions will be called with the address of the current
15036 function and its call site. (On some platforms,
15037 @code{__builtin_return_address} does not work beyond the current
15038 function, so the call site information may not be available to the
15039 profiling functions otherwise.)
15042 void __cyg_profile_func_enter (void *this_fn,
15044 void __cyg_profile_func_exit (void *this_fn,
15048 The first argument is the address of the start of the current function,
15049 which may be looked up exactly in the symbol table.
15051 This instrumentation is also done for functions expanded inline in other
15052 functions. The profiling calls will indicate where, conceptually, the
15053 inline function is entered and exited. This means that addressable
15054 versions of such functions must be available. If all your uses of a
15055 function are expanded inline, this may mean an additional expansion of
15056 code size. If you use @samp{extern inline} in your C code, an
15057 addressable version of such functions must be provided. (This is
15058 normally the case anyways, but if you get lucky and the optimizer always
15059 expands the functions inline, you might have gotten away without
15060 providing static copies.)
15062 A function may be given the attribute @code{no_instrument_function}, in
15063 which case this instrumentation will not be done. This can be used, for
15064 example, for the profiling functions listed above, high-priority
15065 interrupt routines, and any functions from which the profiling functions
15066 cannot safely be called (perhaps signal handlers, if the profiling
15067 routines generate output or allocate memory).
15069 @item -finstrument-functions-exclude-file-list=@var{file},@var{file},@dots{}
15070 @opindex finstrument-functions-exclude-file-list
15072 Set the list of functions that are excluded from instrumentation (see
15073 the description of @code{-finstrument-functions}). If the file that
15074 contains a function definition matches with one of @var{file}, then
15075 that function is not instrumented. The match is done on substrings:
15076 if the @var{file} parameter is a substring of the file name, it is
15077 considered to be a match.
15080 @code{-finstrument-functions-exclude-file-list=/bits/stl,include/sys}
15081 will exclude any inline function defined in files whose pathnames
15082 contain @code{/bits/stl} or @code{include/sys}.
15084 If, for some reason, you want to include letter @code{','} in one of
15085 @var{sym}, write @code{'\,'}. For example,
15086 @code{-finstrument-functions-exclude-file-list='\,\,tmp'}
15087 (note the single quote surrounding the option).
15089 @item -finstrument-functions-exclude-function-list=@var{sym},@var{sym},@dots{}
15090 @opindex finstrument-functions-exclude-function-list
15092 This is similar to @code{-finstrument-functions-exclude-file-list},
15093 but this option sets the list of function names to be excluded from
15094 instrumentation. The function name to be matched is its user-visible
15095 name, such as @code{vector<int> blah(const vector<int> &)}, not the
15096 internal mangled name (e.g., @code{_Z4blahRSt6vectorIiSaIiEE}). The
15097 match is done on substrings: if the @var{sym} parameter is a substring
15098 of the function name, it is considered to be a match.
15100 @item -fstack-check
15101 @opindex fstack-check
15102 Generate code to verify that you do not go beyond the boundary of the
15103 stack. You should specify this flag if you are running in an
15104 environment with multiple threads, but only rarely need to specify it in
15105 a single-threaded environment since stack overflow is automatically
15106 detected on nearly all systems if there is only one stack.
15108 Note that this switch does not actually cause checking to be done; the
15109 operating system must do that. The switch causes generation of code
15110 to ensure that the operating system sees the stack being extended.
15112 @item -fstack-limit-register=@var{reg}
15113 @itemx -fstack-limit-symbol=@var{sym}
15114 @itemx -fno-stack-limit
15115 @opindex fstack-limit-register
15116 @opindex fstack-limit-symbol
15117 @opindex fno-stack-limit
15118 Generate code to ensure that the stack does not grow beyond a certain value,
15119 either the value of a register or the address of a symbol. If the stack
15120 would grow beyond the value, a signal is raised. For most targets,
15121 the signal is raised before the stack overruns the boundary, so
15122 it is possible to catch the signal without taking special precautions.
15124 For instance, if the stack starts at absolute address @samp{0x80000000}
15125 and grows downwards, you can use the flags
15126 @option{-fstack-limit-symbol=__stack_limit} and
15127 @option{-Wl,--defsym,__stack_limit=0x7ffe0000} to enforce a stack limit
15128 of 128KB@. Note that this may only work with the GNU linker.
15130 @cindex aliasing of parameters
15131 @cindex parameters, aliased
15132 @item -fargument-alias
15133 @itemx -fargument-noalias
15134 @itemx -fargument-noalias-global
15135 @itemx -fargument-noalias-anything
15136 @opindex fargument-alias
15137 @opindex fargument-noalias
15138 @opindex fargument-noalias-global
15139 @opindex fargument-noalias-anything
15140 Specify the possible relationships among parameters and between
15141 parameters and global data.
15143 @option{-fargument-alias} specifies that arguments (parameters) may
15144 alias each other and may alias global storage.@*
15145 @option{-fargument-noalias} specifies that arguments do not alias
15146 each other, but may alias global storage.@*
15147 @option{-fargument-noalias-global} specifies that arguments do not
15148 alias each other and do not alias global storage.
15149 @option{-fargument-noalias-anything} specifies that arguments do not
15150 alias any other storage.
15152 Each language will automatically use whatever option is required by
15153 the language standard. You should not need to use these options yourself.
15155 @item -fleading-underscore
15156 @opindex fleading-underscore
15157 This option and its counterpart, @option{-fno-leading-underscore}, forcibly
15158 change the way C symbols are represented in the object file. One use
15159 is to help link with legacy assembly code.
15161 @strong{Warning:} the @option{-fleading-underscore} switch causes GCC to
15162 generate code that is not binary compatible with code generated without that
15163 switch. Use it to conform to a non-default application binary interface.
15164 Not all targets provide complete support for this switch.
15166 @item -ftls-model=@var{model}
15167 @opindex ftls-model
15168 Alter the thread-local storage model to be used (@pxref{Thread-Local}).
15169 The @var{model} argument should be one of @code{global-dynamic},
15170 @code{local-dynamic}, @code{initial-exec} or @code{local-exec}.
15172 The default without @option{-fpic} is @code{initial-exec}; with
15173 @option{-fpic} the default is @code{global-dynamic}.
15175 @item -fvisibility=@var{default|internal|hidden|protected}
15176 @opindex fvisibility
15177 Set the default ELF image symbol visibility to the specified option---all
15178 symbols will be marked with this unless overridden within the code.
15179 Using this feature can very substantially improve linking and
15180 load times of shared object libraries, produce more optimized
15181 code, provide near-perfect API export and prevent symbol clashes.
15182 It is @strong{strongly} recommended that you use this in any shared objects
15185 Despite the nomenclature, @code{default} always means public ie;
15186 available to be linked against from outside the shared object.
15187 @code{protected} and @code{internal} are pretty useless in real-world
15188 usage so the only other commonly used option will be @code{hidden}.
15189 The default if @option{-fvisibility} isn't specified is
15190 @code{default}, i.e., make every
15191 symbol public---this causes the same behavior as previous versions of
15194 A good explanation of the benefits offered by ensuring ELF
15195 symbols have the correct visibility is given by ``How To Write
15196 Shared Libraries'' by Ulrich Drepper (which can be found at
15197 @w{@uref{http://people.redhat.com/~drepper/}})---however a superior
15198 solution made possible by this option to marking things hidden when
15199 the default is public is to make the default hidden and mark things
15200 public. This is the norm with DLL's on Windows and with @option{-fvisibility=hidden}
15201 and @code{__attribute__ ((visibility("default")))} instead of
15202 @code{__declspec(dllexport)} you get almost identical semantics with
15203 identical syntax. This is a great boon to those working with
15204 cross-platform projects.
15206 For those adding visibility support to existing code, you may find
15207 @samp{#pragma GCC visibility} of use. This works by you enclosing
15208 the declarations you wish to set visibility for with (for example)
15209 @samp{#pragma GCC visibility push(hidden)} and
15210 @samp{#pragma GCC visibility pop}.
15211 Bear in mind that symbol visibility should be viewed @strong{as
15212 part of the API interface contract} and thus all new code should
15213 always specify visibility when it is not the default ie; declarations
15214 only for use within the local DSO should @strong{always} be marked explicitly
15215 as hidden as so to avoid PLT indirection overheads---making this
15216 abundantly clear also aids readability and self-documentation of the code.
15217 Note that due to ISO C++ specification requirements, operator new and
15218 operator delete must always be of default visibility.
15220 Be aware that headers from outside your project, in particular system
15221 headers and headers from any other library you use, may not be
15222 expecting to be compiled with visibility other than the default. You
15223 may need to explicitly say @samp{#pragma GCC visibility push(default)}
15224 before including any such headers.
15226 @samp{extern} declarations are not affected by @samp{-fvisibility}, so
15227 a lot of code can be recompiled with @samp{-fvisibility=hidden} with
15228 no modifications. However, this means that calls to @samp{extern}
15229 functions with no explicit visibility will use the PLT, so it is more
15230 effective to use @samp{__attribute ((visibility))} and/or
15231 @samp{#pragma GCC visibility} to tell the compiler which @samp{extern}
15232 declarations should be treated as hidden.
15234 Note that @samp{-fvisibility} does affect C++ vague linkage
15235 entities. This means that, for instance, an exception class that will
15236 be thrown between DSOs must be explicitly marked with default
15237 visibility so that the @samp{type_info} nodes will be unified between
15240 An overview of these techniques, their benefits and how to use them
15241 is at @w{@uref{http://gcc.gnu.org/wiki/Visibility}}.
15247 @node Environment Variables
15248 @section Environment Variables Affecting GCC
15249 @cindex environment variables
15251 @c man begin ENVIRONMENT
15252 This section describes several environment variables that affect how GCC
15253 operates. Some of them work by specifying directories or prefixes to use
15254 when searching for various kinds of files. Some are used to specify other
15255 aspects of the compilation environment.
15257 Note that you can also specify places to search using options such as
15258 @option{-B}, @option{-I} and @option{-L} (@pxref{Directory Options}). These
15259 take precedence over places specified using environment variables, which
15260 in turn take precedence over those specified by the configuration of GCC@.
15261 @xref{Driver,, Controlling the Compilation Driver @file{gcc}, gccint,
15262 GNU Compiler Collection (GCC) Internals}.
15267 @c @itemx LC_COLLATE
15269 @c @itemx LC_MONETARY
15270 @c @itemx LC_NUMERIC
15275 @c @findex LC_COLLATE
15276 @findex LC_MESSAGES
15277 @c @findex LC_MONETARY
15278 @c @findex LC_NUMERIC
15282 These environment variables control the way that GCC uses
15283 localization information that allow GCC to work with different
15284 national conventions. GCC inspects the locale categories
15285 @env{LC_CTYPE} and @env{LC_MESSAGES} if it has been configured to do
15286 so. These locale categories can be set to any value supported by your
15287 installation. A typical value is @samp{en_GB.UTF-8} for English in the United
15288 Kingdom encoded in UTF-8.
15290 The @env{LC_CTYPE} environment variable specifies character
15291 classification. GCC uses it to determine the character boundaries in
15292 a string; this is needed for some multibyte encodings that contain quote
15293 and escape characters that would otherwise be interpreted as a string
15296 The @env{LC_MESSAGES} environment variable specifies the language to
15297 use in diagnostic messages.
15299 If the @env{LC_ALL} environment variable is set, it overrides the value
15300 of @env{LC_CTYPE} and @env{LC_MESSAGES}; otherwise, @env{LC_CTYPE}
15301 and @env{LC_MESSAGES} default to the value of the @env{LANG}
15302 environment variable. If none of these variables are set, GCC
15303 defaults to traditional C English behavior.
15307 If @env{TMPDIR} is set, it specifies the directory to use for temporary
15308 files. GCC uses temporary files to hold the output of one stage of
15309 compilation which is to be used as input to the next stage: for example,
15310 the output of the preprocessor, which is the input to the compiler
15313 @item GCC_EXEC_PREFIX
15314 @findex GCC_EXEC_PREFIX
15315 If @env{GCC_EXEC_PREFIX} is set, it specifies a prefix to use in the
15316 names of the subprograms executed by the compiler. No slash is added
15317 when this prefix is combined with the name of a subprogram, but you can
15318 specify a prefix that ends with a slash if you wish.
15320 If @env{GCC_EXEC_PREFIX} is not set, GCC will attempt to figure out
15321 an appropriate prefix to use based on the pathname it was invoked with.
15323 If GCC cannot find the subprogram using the specified prefix, it
15324 tries looking in the usual places for the subprogram.
15326 The default value of @env{GCC_EXEC_PREFIX} is
15327 @file{@var{prefix}/lib/gcc/} where @var{prefix} is the prefix to
15328 the installed compiler. In many cases @var{prefix} is the value
15329 of @code{prefix} when you ran the @file{configure} script.
15331 Other prefixes specified with @option{-B} take precedence over this prefix.
15333 This prefix is also used for finding files such as @file{crt0.o} that are
15336 In addition, the prefix is used in an unusual way in finding the
15337 directories to search for header files. For each of the standard
15338 directories whose name normally begins with @samp{/usr/local/lib/gcc}
15339 (more precisely, with the value of @env{GCC_INCLUDE_DIR}), GCC tries
15340 replacing that beginning with the specified prefix to produce an
15341 alternate directory name. Thus, with @option{-Bfoo/}, GCC will search
15342 @file{foo/bar} where it would normally search @file{/usr/local/lib/bar}.
15343 These alternate directories are searched first; the standard directories
15344 come next. If a standard directory begins with the configured
15345 @var{prefix} then the value of @var{prefix} is replaced by
15346 @env{GCC_EXEC_PREFIX} when looking for header files.
15348 @item COMPILER_PATH
15349 @findex COMPILER_PATH
15350 The value of @env{COMPILER_PATH} is a colon-separated list of
15351 directories, much like @env{PATH}. GCC tries the directories thus
15352 specified when searching for subprograms, if it can't find the
15353 subprograms using @env{GCC_EXEC_PREFIX}.
15356 @findex LIBRARY_PATH
15357 The value of @env{LIBRARY_PATH} is a colon-separated list of
15358 directories, much like @env{PATH}. When configured as a native compiler,
15359 GCC tries the directories thus specified when searching for special
15360 linker files, if it can't find them using @env{GCC_EXEC_PREFIX}. Linking
15361 using GCC also uses these directories when searching for ordinary
15362 libraries for the @option{-l} option (but directories specified with
15363 @option{-L} come first).
15367 @cindex locale definition
15368 This variable is used to pass locale information to the compiler. One way in
15369 which this information is used is to determine the character set to be used
15370 when character literals, string literals and comments are parsed in C and C++.
15371 When the compiler is configured to allow multibyte characters,
15372 the following values for @env{LANG} are recognized:
15376 Recognize JIS characters.
15378 Recognize SJIS characters.
15380 Recognize EUCJP characters.
15383 If @env{LANG} is not defined, or if it has some other value, then the
15384 compiler will use mblen and mbtowc as defined by the default locale to
15385 recognize and translate multibyte characters.
15389 Some additional environments variables affect the behavior of the
15392 @include cppenv.texi
15396 @node Precompiled Headers
15397 @section Using Precompiled Headers
15398 @cindex precompiled headers
15399 @cindex speed of compilation
15401 Often large projects have many header files that are included in every
15402 source file. The time the compiler takes to process these header files
15403 over and over again can account for nearly all of the time required to
15404 build the project. To make builds faster, GCC allows users to
15405 `precompile' a header file; then, if builds can use the precompiled
15406 header file they will be much faster.
15408 To create a precompiled header file, simply compile it as you would any
15409 other file, if necessary using the @option{-x} option to make the driver
15410 treat it as a C or C++ header file. You will probably want to use a
15411 tool like @command{make} to keep the precompiled header up-to-date when
15412 the headers it contains change.
15414 A precompiled header file will be searched for when @code{#include} is
15415 seen in the compilation. As it searches for the included file
15416 (@pxref{Search Path,,Search Path,cpp,The C Preprocessor}) the
15417 compiler looks for a precompiled header in each directory just before it
15418 looks for the include file in that directory. The name searched for is
15419 the name specified in the @code{#include} with @samp{.gch} appended. If
15420 the precompiled header file can't be used, it is ignored.
15422 For instance, if you have @code{#include "all.h"}, and you have
15423 @file{all.h.gch} in the same directory as @file{all.h}, then the
15424 precompiled header file will be used if possible, and the original
15425 header will be used otherwise.
15427 Alternatively, you might decide to put the precompiled header file in a
15428 directory and use @option{-I} to ensure that directory is searched
15429 before (or instead of) the directory containing the original header.
15430 Then, if you want to check that the precompiled header file is always
15431 used, you can put a file of the same name as the original header in this
15432 directory containing an @code{#error} command.
15434 This also works with @option{-include}. So yet another way to use
15435 precompiled headers, good for projects not designed with precompiled
15436 header files in mind, is to simply take most of the header files used by
15437 a project, include them from another header file, precompile that header
15438 file, and @option{-include} the precompiled header. If the header files
15439 have guards against multiple inclusion, they will be skipped because
15440 they've already been included (in the precompiled header).
15442 If you need to precompile the same header file for different
15443 languages, targets, or compiler options, you can instead make a
15444 @emph{directory} named like @file{all.h.gch}, and put each precompiled
15445 header in the directory, perhaps using @option{-o}. It doesn't matter
15446 what you call the files in the directory, every precompiled header in
15447 the directory will be considered. The first precompiled header
15448 encountered in the directory that is valid for this compilation will
15449 be used; they're searched in no particular order.
15451 There are many other possibilities, limited only by your imagination,
15452 good sense, and the constraints of your build system.
15454 A precompiled header file can be used only when these conditions apply:
15458 Only one precompiled header can be used in a particular compilation.
15461 A precompiled header can't be used once the first C token is seen. You
15462 can have preprocessor directives before a precompiled header; you can
15463 even include a precompiled header from inside another header, so long as
15464 there are no C tokens before the @code{#include}.
15467 The precompiled header file must be produced for the same language as
15468 the current compilation. You can't use a C precompiled header for a C++
15472 The precompiled header file must have been produced by the same compiler
15473 binary as the current compilation is using.
15476 Any macros defined before the precompiled header is included must
15477 either be defined in the same way as when the precompiled header was
15478 generated, or must not affect the precompiled header, which usually
15479 means that they don't appear in the precompiled header at all.
15481 The @option{-D} option is one way to define a macro before a
15482 precompiled header is included; using a @code{#define} can also do it.
15483 There are also some options that define macros implicitly, like
15484 @option{-O} and @option{-Wdeprecated}; the same rule applies to macros
15487 @item If debugging information is output when using the precompiled
15488 header, using @option{-g} or similar, the same kind of debugging information
15489 must have been output when building the precompiled header. However,
15490 a precompiled header built using @option{-g} can be used in a compilation
15491 when no debugging information is being output.
15493 @item The same @option{-m} options must generally be used when building
15494 and using the precompiled header. @xref{Submodel Options},
15495 for any cases where this rule is relaxed.
15497 @item Each of the following options must be the same when building and using
15498 the precompiled header:
15500 @gccoptlist{-fexceptions -funit-at-a-time}
15503 Some other command-line options starting with @option{-f},
15504 @option{-p}, or @option{-O} must be defined in the same way as when
15505 the precompiled header was generated. At present, it's not clear
15506 which options are safe to change and which are not; the safest choice
15507 is to use exactly the same options when generating and using the
15508 precompiled header. The following are known to be safe:
15510 @gccoptlist{-fmessage-length= -fpreprocessed -fsched-interblock @gol
15511 -fsched-spec -fsched-spec-load -fsched-spec-load-dangerous @gol
15512 -fsched-verbose=<number> -fschedule-insns -fvisibility= @gol
15517 For all of these except the last, the compiler will automatically
15518 ignore the precompiled header if the conditions aren't met. If you
15519 find an option combination that doesn't work and doesn't cause the
15520 precompiled header to be ignored, please consider filing a bug report,
15523 If you do use differing options when generating and using the
15524 precompiled header, the actual behavior will be a mixture of the
15525 behavior for the options. For instance, if you use @option{-g} to
15526 generate the precompiled header but not when using it, you may or may
15527 not get debugging information for routines in the precompiled header.
15529 @node Running Protoize
15530 @section Running Protoize
15532 The program @code{protoize} is an optional part of GCC@. You can use
15533 it to add prototypes to a program, thus converting the program to ISO
15534 C in one respect. The companion program @code{unprotoize} does the
15535 reverse: it removes argument types from any prototypes that are found.
15537 When you run these programs, you must specify a set of source files as
15538 command line arguments. The conversion programs start out by compiling
15539 these files to see what functions they define. The information gathered
15540 about a file @var{foo} is saved in a file named @file{@var{foo}.X}.
15542 After scanning comes actual conversion. The specified files are all
15543 eligible to be converted; any files they include (whether sources or
15544 just headers) are eligible as well.
15546 But not all the eligible files are converted. By default,
15547 @code{protoize} and @code{unprotoize} convert only source and header
15548 files in the current directory. You can specify additional directories
15549 whose files should be converted with the @option{-d @var{directory}}
15550 option. You can also specify particular files to exclude with the
15551 @option{-x @var{file}} option. A file is converted if it is eligible, its
15552 directory name matches one of the specified directory names, and its
15553 name within the directory has not been excluded.
15555 Basic conversion with @code{protoize} consists of rewriting most
15556 function definitions and function declarations to specify the types of
15557 the arguments. The only ones not rewritten are those for varargs
15560 @code{protoize} optionally inserts prototype declarations at the
15561 beginning of the source file, to make them available for any calls that
15562 precede the function's definition. Or it can insert prototype
15563 declarations with block scope in the blocks where undeclared functions
15566 Basic conversion with @code{unprotoize} consists of rewriting most
15567 function declarations to remove any argument types, and rewriting
15568 function definitions to the old-style pre-ISO form.
15570 Both conversion programs print a warning for any function declaration or
15571 definition that they can't convert. You can suppress these warnings
15574 The output from @code{protoize} or @code{unprotoize} replaces the
15575 original source file. The original file is renamed to a name ending
15576 with @samp{.save} (for DOS, the saved filename ends in @samp{.sav}
15577 without the original @samp{.c} suffix). If the @samp{.save} (@samp{.sav}
15578 for DOS) file already exists, then the source file is simply discarded.
15580 @code{protoize} and @code{unprotoize} both depend on GCC itself to
15581 scan the program and collect information about the functions it uses.
15582 So neither of these programs will work until GCC is installed.
15584 Here is a table of the options you can use with @code{protoize} and
15585 @code{unprotoize}. Each option works with both programs unless
15589 @item -B @var{directory}
15590 Look for the file @file{SYSCALLS.c.X} in @var{directory}, instead of the
15591 usual directory (normally @file{/usr/local/lib}). This file contains
15592 prototype information about standard system functions. This option
15593 applies only to @code{protoize}.
15595 @item -c @var{compilation-options}
15596 Use @var{compilation-options} as the options when running @command{gcc} to
15597 produce the @samp{.X} files. The special option @option{-aux-info} is
15598 always passed in addition, to tell @command{gcc} to write a @samp{.X} file.
15600 Note that the compilation options must be given as a single argument to
15601 @code{protoize} or @code{unprotoize}. If you want to specify several
15602 @command{gcc} options, you must quote the entire set of compilation options
15603 to make them a single word in the shell.
15605 There are certain @command{gcc} arguments that you cannot use, because they
15606 would produce the wrong kind of output. These include @option{-g},
15607 @option{-O}, @option{-c}, @option{-S}, and @option{-o} If you include these in
15608 the @var{compilation-options}, they are ignored.
15611 Rename files to end in @samp{.C} (@samp{.cc} for DOS-based file
15612 systems) instead of @samp{.c}. This is convenient if you are converting
15613 a C program to C++. This option applies only to @code{protoize}.
15616 Add explicit global declarations. This means inserting explicit
15617 declarations at the beginning of each source file for each function
15618 that is called in the file and was not declared. These declarations
15619 precede the first function definition that contains a call to an
15620 undeclared function. This option applies only to @code{protoize}.
15622 @item -i @var{string}
15623 Indent old-style parameter declarations with the string @var{string}.
15624 This option applies only to @code{protoize}.
15626 @code{unprotoize} converts prototyped function definitions to old-style
15627 function definitions, where the arguments are declared between the
15628 argument list and the initial @samp{@{}. By default, @code{unprotoize}
15629 uses five spaces as the indentation. If you want to indent with just
15630 one space instead, use @option{-i " "}.
15633 Keep the @samp{.X} files. Normally, they are deleted after conversion
15637 Add explicit local declarations. @code{protoize} with @option{-l} inserts
15638 a prototype declaration for each function in each block which calls the
15639 function without any declaration. This option applies only to
15643 Make no real changes. This mode just prints information about the conversions
15644 that would have been done without @option{-n}.
15647 Make no @samp{.save} files. The original files are simply deleted.
15648 Use this option with caution.
15650 @item -p @var{program}
15651 Use the program @var{program} as the compiler. Normally, the name
15652 @file{gcc} is used.
15655 Work quietly. Most warnings are suppressed.
15658 Print the version number, just like @option{-v} for @command{gcc}.
15661 If you need special compiler options to compile one of your program's
15662 source files, then you should generate that file's @samp{.X} file
15663 specially, by running @command{gcc} on that source file with the
15664 appropriate options and the option @option{-aux-info}. Then run
15665 @code{protoize} on the entire set of files. @code{protoize} will use
15666 the existing @samp{.X} file because it is newer than the source file.
15670 gcc -Dfoo=bar file1.c -aux-info file1.X
15675 You need to include the special files along with the rest in the
15676 @code{protoize} command, even though their @samp{.X} files already
15677 exist, because otherwise they won't get converted.
15679 @xref{Protoize Caveats}, for more information on how to use
15680 @code{protoize} successfully.