diff options
Diffstat (limited to 'contrib/gcc/doc/invoke.texi')
| -rw-r--r-- | contrib/gcc/doc/invoke.texi | 3404 |
1 files changed, 1913 insertions, 1491 deletions
diff --git a/contrib/gcc/doc/invoke.texi b/contrib/gcc/doc/invoke.texi index 6a12890..7e88bd5 100644 --- a/contrib/gcc/doc/invoke.texi +++ b/contrib/gcc/doc/invoke.texi @@ -1,12 +1,12 @@ @c Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, -@c 2000, 2001, 2002, 2003 Free Software Foundation, Inc. +@c 2000, 2001, 2002, 2003, 2004 Free Software Foundation, Inc. @c This is part of the GCC manual. @c For copying conditions, see the file gcc.texi. @ignore @c man begin COPYRIGHT Copyright @copyright{} 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, -1998, 1999, 2000, 2001, 2002, 2003 Free Software Foundation, Inc. +1998, 1999, 2000, 2001, 2002, 2003, 2004 Free Software Foundation, Inc. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or @@ -140,6 +140,7 @@ only one of these two forms, whichever one is not the default. * Code Gen Options:: Specifying conventions for function calls, data layout and register usage. * Environment Variables:: Env vars that affect GCC. +* Precompiled Headers:: Compiling a header once, and using it many times. * Running Protoize:: Automatically adding or removing function prototypes. @end menu @@ -171,10 +172,9 @@ in the following sections. @item C++ Language Options @xref{C++ Dialect Options,,Options Controlling C++ Dialect}. @gccoptlist{-fabi-version=@var{n} -fno-access-control -fcheck-new @gol --fconserve-space -fno-const-strings -fdollars-in-identifiers @gol +-fconserve-space -fno-const-strings @gol -fno-elide-constructors @gol --fno-enforce-eh-specs -fexternal-templates @gol --falt-external-templates @gol +-fno-enforce-eh-specs @gol -ffor-scope -fno-for-scope -fno-gnu-keywords @gol -fno-implicit-templates @gol -fno-implicit-inline-templates @gol @@ -182,7 +182,7 @@ in the following sections. -fno-nonansi-builtins -fno-operator-names @gol -fno-optional-diags -fpermissive @gol -frepo -fno-rtti -fstats -ftemplate-depth-@var{n} @gol --fuse-cxa-atexit -fvtable-gc -fno-weak -nostdinc++ @gol +-fuse-cxa-atexit -fno-weak -nostdinc++ @gol -fno-default-inline -Wabi -Wctor-dtor-privacy @gol -Wnon-virtual-dtor -Wreorder @gol -Weffc++ -Wno-deprecated @gol @@ -192,33 +192,39 @@ in the following sections. @item Objective-C Language Options @xref{Objective-C Dialect Options,,Options Controlling Objective-C Dialect}. -@gccoptlist{-fconstant-string-class=@var{class-name} @gol --fgnu-runtime -fnext-runtime -gen-decls @gol --Wno-protocol -Wselector -Wundeclared-selector} +@gccoptlist{ +-fconstant-string-class=@var{class-name} @gol +-fgnu-runtime -fnext-runtime @gol +-fno-nil-receivers @gol +-fobjc-exceptions @gol +-freplace-objc-classes @gol +-fzero-link @gol +-gen-decls @gol +-Wno-protocol -Wselector -Wundeclared-selector} @item Language Independent Options @xref{Language Independent Options,,Options to Control Diagnostic Messages Formatting}. -@gccoptlist{-fmessage-length=@var{n} @gol +@gccoptlist{-fmessage-length=@var{n} @gol -fdiagnostics-show-location=@r{[}once@r{|}every-line@r{]}} @item Warning Options @xref{Warning Options,,Options to Request or Suppress Warnings}. @gccoptlist{-fsyntax-only -pedantic -pedantic-errors @gol --w -W -Wall -Waggregate-return @gol +-w -Wextra -Wall -Waggregate-return @gol -Wcast-align -Wcast-qual -Wchar-subscripts -Wcomment @gol -Wconversion -Wno-deprecated-declarations @gol --Wdisabled-optimization -Wno-div-by-zero -Werror @gol +-Wdisabled-optimization -Wno-div-by-zero -Wendif-labels @gol +-Werror -Werror-implicit-function-declaration @gol -Wfloat-equal -Wformat -Wformat=2 @gol --Wformat-nonliteral -Wformat-security @gol --Wimplicit -Wimplicit-int @gol --Wimplicit-function-declaration @gol --Werror-implicit-function-declaration @gol --Wimport -Winline -Wno-endif-labels @gol +-Wno-format-extra-args -Wformat-nonliteral @gol +-Wformat-security -Wformat-y2k @gol +-Wimplicit -Wimplicit-function-declaration -Wimplicit-int @gol +-Wimport -Wno-import -Winit-self -Winline @gol +-Wno-invalid-offsetof -Winvalid-pch @gol -Wlarger-than-@var{len} -Wlong-long @gol -Wmain -Wmissing-braces @gol -Wmissing-format-attribute -Wmissing-noreturn @gol --Wno-multichar -Wno-format-extra-args -Wno-format-y2k @gol --Wno-import -Wnonnull -Wpacked -Wpadded @gol +-Wno-multichar -Wnonnull -Wpacked -Wpadded @gol -Wparentheses -Wpointer-arith -Wredundant-decls @gol -Wreturn-type -Wsequence-point -Wshadow @gol -Wsign-compare -Wstrict-aliasing @gol @@ -230,8 +236,9 @@ in the following sections. @item C-only Warning Options @gccoptlist{-Wbad-function-cast -Wmissing-declarations @gol --Wmissing-prototypes -Wnested-externs @gol --Wstrict-prototypes -Wtraditional} +-Wmissing-prototypes -Wnested-externs -Wold-style-definition @gol +-Wstrict-prototypes -Wtraditional @gol +-Wdeclaration-after-statement} @item Debugging Options @xref{Debugging Options,,Options for Debugging Your Program or GCC}. @@ -241,10 +248,11 @@ in the following sections. -fdump-tree-original@r{[}-@var{n}@r{]} @gol -fdump-tree-optimized@r{[}-@var{n}@r{]} @gol -fdump-tree-inlined@r{[}-@var{n}@r{]} @gol --feliminate-dwarf2-dups -fmem-report @gol --fprofile-arcs -frandom-seed=@var{n} @gol --fsched-verbose=@var{n} -ftest-coverage -ftime-report @gol --g -g@var{level} -gcoff -gdwarf -gdwarf-1 -gdwarf-1+ -gdwarf-2 @gol +-feliminate-dwarf2-dups -feliminate-unused-debug-types @gol +-feliminate-unused-debug-symbols -fmem-report -fprofile-arcs @gol +-frandom-seed=@var{string} -fsched-verbose=@var{n} @gol +-ftest-coverage -ftime-report @gol +-g -g@var{level} -gcoff -gdwarf-2 @gol -ggdb -gstabs -gstabs+ -gvms -gxcoff -gxcoff+ @gol -p -pg -print-file-name=@var{library} -print-libgcc-file-name @gol -print-multi-directory -print-multi-lib @gol @@ -255,13 +263,14 @@ in the following sections. @xref{Optimize Options,,Options that Control Optimization}. @gccoptlist{-falign-functions=@var{n} -falign-jumps=@var{n} @gol -falign-labels=@var{n} -falign-loops=@var{n} @gol --fbranch-probabilities -fcaller-saves -fcprop-registers @gol +-fbranch-probabilities -fprofile-values -fvpt -fbranch-target-load-optimize @gol +-fbranch-target-load-optimize2 -fcaller-saves -fcprop-registers @gol -fcse-follow-jumps -fcse-skip-blocks -fdata-sections @gol -fdelayed-branch -fdelete-null-pointer-checks @gol -fexpensive-optimizations -ffast-math -ffloat-store @gol -fforce-addr -fforce-mem -ffunction-sections @gol --fgcse -fgcse-lm -fgcse-sm -floop-optimize -fcrossjumping @gol --fif-conversion -fif-conversion2 @gol +-fgcse -fgcse-lm -fgcse-sm -fgcse-las -floop-optimize @gol +-fcrossjumping -fif-conversion -fif-conversion2 @gol -finline-functions -finline-limit=@var{n} -fkeep-inline-functions @gol -fkeep-static-consts -fmerge-constants -fmerge-all-constants @gol -fmove-all-movables -fnew-ra -fno-branch-count-reg @gol @@ -272,21 +281,26 @@ in the following sections. -fno-trapping-math -fno-zero-initialized-in-bss @gol -fomit-frame-pointer -foptimize-register-move @gol -foptimize-sibling-calls -fprefetch-loop-arrays @gol +-fprofile-generate -fprofile-use @gol -freduce-all-givs -fregmove -frename-registers @gol -freorder-blocks -freorder-functions @gol -frerun-cse-after-loop -frerun-loop-opt @gol --fschedule-insns -fschedule-insns2 @gol +-frounding-math -fschedule-insns -fschedule-insns2 @gol -fno-sched-interblock -fno-sched-spec -fsched-spec-load @gol --fsched-spec-load-dangerous -fsignaling-nans @gol --fsingle-precision-constant -fssa -fssa-ccp -fssa-dce @gol +-fsched-spec-load-dangerous @gol +-fsched-stalled-insns=@var{n} -sched-stalled-insns-dep=@var{n} @gol +-fsched2-use-superblocks @gol +-fsched2-use-traces -fsignaling-nans @gol +-fsingle-precision-constant @gol -fstrength-reduce -fstrict-aliasing -ftracer -fthread-jumps @gol --funroll-all-loops -funroll-loops @gol ---param @var{name}=@var{value} @gol +-funroll-all-loops -funroll-loops -fpeel-loops @gol +-funswitch-loops -fold-unroll-loops -fold-unroll-all-loops @gol +--param @var{name}=@var{value} -O -O0 -O1 -O2 -O3 -Os} @item Preprocessor Options @xref{Preprocessor Options,,Options Controlling the Preprocessor}. -@gccoptlist{-$ -A@var{question}=@var{answer} @gol +@gccoptlist{-A@var{question}=@var{answer} @gol -A-@var{question}@r{[}=@var{answer}@r{]} @gol -C -dD -dI -dM -dN @gol -D@var{macro}@r{[}=@var{defn}@r{]} -E -H @gol @@ -294,17 +308,19 @@ in the following sections. -include @var{file} -imacros @var{file} @gol -iprefix @var{file} -iwithprefix @var{dir} @gol -iwithprefixbefore @var{dir} -isystem @var{dir} @gol --M -MM -MF -MG -MP -MQ -MT -nostdinc -P -remap @gol --trigraphs -undef -U@var{macro} -Wp,@var{option}} +-M -MM -MF -MG -MP -MQ -MT -nostdinc @gol +-P -fworking-directory -remap @gol +-trigraphs -undef -U@var{macro} -Wp,@var{option} @gol +-Xpreprocessor @var{option}} @item Assembler Option @xref{Assembler Options,,Passing Options to the Assembler}. -@gccoptlist{-Wa,@var{option}} +@gccoptlist{-Wa,@var{option} -Xassembler @var{option}} @item Linker Options @xref{Link Options,,Options for Linking}. @gccoptlist{@var{object-file-name} -l@var{library} @gol --nostartfiles -nodefaultlibs -nostdlib @gol +-nostartfiles -nodefaultlibs -nostdlib -pie @gol -s -static -static-libgcc -shared -shared-libgcc -symbolic @gol -Wl,@var{option} -Xlinker @var{option} @gol -u @var{symbol}} @@ -324,11 +340,12 @@ in the following sections. @emph{M680x0 Options} @gccoptlist{-m68000 -m68020 -m68020-40 -m68020-60 -m68030 -m68040 @gol -m68060 -mcpu32 -m5200 -m68881 -mbitfield -mc68000 -mc68020 @gol --mfpa -mnobitfield -mrtd -mshort -msoft-float -mpcrel @gol --malign-int -mstrict-align} +-mnobitfield -mrtd -mshort -msoft-float -mpcrel @gol +-malign-int -mstrict-align -msep-data -mno-sep-data @gol +-mshared-library-id=n -mid-shared-library -mno-id-shared-library} @emph{M68hc1x Options} -@gccoptlist{-m6811 -m6812 -m68hc11 -m68hc12 -m68hcs12 @gol +@gccoptlist{-m6811 -m6812 -m68hc11 -m68hc12 -m68hcs12 @gol -mauto-incdec -minmax -mlong-calls -mshort @gol -msoft-reg-count=@var{count}} @@ -339,15 +356,18 @@ in the following sections. @gccoptlist{-mcpu=@var{cpu-type} @gol -mtune=@var{cpu-type} @gol -mcmodel=@var{code-model} @gol --m32 -m64 @gol --mapp-regs -mbroken-saverestore -mcypress @gol --mfaster-structs -mflat @gol --mfpu -mhard-float -mhard-quad-float @gol --mimpure-text -mlittle-endian -mlive-g0 -mno-app-regs @gol --mno-faster-structs -mno-flat -mno-fpu @gol --mno-impure-text -mno-stack-bias -mno-unaligned-doubles @gol --msoft-float -msoft-quad-float -msparclite -mstack-bias @gol --msupersparc -munaligned-doubles -mv8} +-m32 -m64 -mapp-regs -mno-app-regs @gol +-mfaster-structs -mno-faster-structs @gol +-mflat -mno-flat -mfpu -mno-fpu @gol +-mhard-float -msoft-float @gol +-mhard-quad-float -msoft-quad-float @gol +-mimpure-text -mno-impure-text -mlittle-endian @gol +-mstack-bias -mno-stack-bias @gol +-munaligned-doubles -mno-unaligned-doubles @gol +-mv8plus -mno-v8plus -mvis -mno-vis @gol +-mcypress -mf930 -mf934 @gol +-msparclite -msupersparc -mv8 +-threads -pthreads} @emph{ARM Options} @gccoptlist{-mapcs-frame -mno-apcs-frame @gol @@ -367,34 +387,29 @@ in the following sections. -msingle-pic-base -mno-single-pic-base @gol -mpic-register=@var{reg} @gol -mnop-fun-dllimport @gol +-mcirrus-fix-invalid-insns -mno-cirrus-fix-invalid-insns @gol -mpoke-function-name @gol -mthumb -marm @gol -mtpcs-frame -mtpcs-leaf-frame @gol -mcaller-super-interworking -mcallee-super-interworking} -@emph{MN10200 Options} -@gccoptlist{-mrelax} - @emph{MN10300 Options} @gccoptlist{-mmult-bug -mno-mult-bug @gol -mam33 -mno-am33 @gol +-mam33-2 -mno-am33-2 @gol -mno-crt0 -mrelax} @emph{M32R/D Options} -@gccoptlist{-m32rx -m32r -mcode-model=@var{model-type} @gol --msdata=@var{sdata-type} -G @var{num}} - -@emph{M88K Options} -@gccoptlist{-m88000 -m88100 -m88110 -mbig-pic @gol --mcheck-zero-division -mhandle-large-shift @gol --midentify-revision -mno-check-zero-division @gol --mno-ocs-debug-info -mno-ocs-frame-position @gol --mno-optimize-arg-area -mno-serialize-volatile @gol --mno-underscores -mocs-debug-info @gol --mocs-frame-position -moptimize-arg-area @gol --mserialize-volatile -mshort-data-@var{num} -msvr3 @gol --msvr4 -mtrap-large-shift -muse-div-instruction @gol --mversion-03.00 -mwarn-passed-structs} +@gccoptlist{-m32r2 -m32rx -m32r @gol +-mdebug @gol +-malign-loops -mno-align-loops @gol +-missue-rate=@var{number} @gol +-mbranch-cost=@var{number} @gol +-mmodel=@var{code-size-model-type} @gol +-msdata=@var{sdata-type} @gol +-mno-flush-func -mflush-func=@var{name} @gol +-mno-flush-trap -mflush-trap=@var{number} @gol +-G @var{num}} @emph{RS/6000 and PowerPC Options} @gccoptlist{-mcpu=@var{cpu-type} @gol @@ -407,85 +422,88 @@ in the following sections. -mnew-mnemonics -mold-mnemonics @gol -mfull-toc -mminimal-toc -mno-fp-in-toc -mno-sum-in-toc @gol -m64 -m32 -mxl-call -mno-xl-call -mpe @gol +-malign-power -malign-natural @gol -msoft-float -mhard-float -mmultiple -mno-multiple @gol -mstring -mno-string -mupdate -mno-update @gol -mfused-madd -mno-fused-madd -mbit-align -mno-bit-align @gol -mstrict-align -mno-strict-align -mrelocatable @gol -mno-relocatable -mrelocatable-lib -mno-relocatable-lib @gol -mtoc -mno-toc -mlittle -mlittle-endian -mbig -mbig-endian @gol --mcall-aix -mcall-sysv -mcall-netbsd @gol +-mdynamic-no-pic @gol +-mprioritize-restricted-insns=@var{priority} @gol +-msched-costly-dep=@var{dependence_type} @gol +-minsert-sched-nops=@var{scheme} @gol +-mcall-sysv -mcall-netbsd @gol -maix-struct-return -msvr4-struct-return @gol -mabi=altivec -mabi=no-altivec @gol -mabi=spe -mabi=no-spe @gol -misel=yes -misel=no @gol +-mspe=yes -mspe=no @gol +-mfloat-gprs=yes -mfloat-gprs=no @gol -mprototype -mno-prototype @gol -msim -mmvme -mads -myellowknife -memb -msdata @gol -msdata=@var{opt} -mvxworks -mwindiss -G @var{num} -pthread} @emph{Darwin Options} -@gccoptlist{ --all_load -allowable_client -arch -arch_errors_fatal @gol --arch_only -bind_at_load -bundle -bundle_loader @gol --client_name -compatibility_version -current_version @gol --dependency-file -dylib_file -dylinker_install_name @gol --dynamic -dynamiclib -exported_symbols_list @gol --filelist -flat_namespace -force_cpusubtype_ALL @gol --force_flat_namespace -headerpad_max_install_names @gol --image_base -init -install_name -keep_private_externs @gol --multi_module -multiply_defined -multiply_defined_unused @gol --noall_load -nomultidefs -noprebind -noseglinkedit @gol --pagezero_size -prebind -prebind_all_twolevel_modules @gol --private_bundle -read_only_relocs -sectalign @gol --sectobjectsymbols -whyload -seg1addr @gol --sectcreate -sectobjectsymbols -sectorder @gol --seg_addr_table -seg_addr_table_filename -seglinkedit @gol --segprot -segs_read_only_addr -segs_read_write_addr @gol --single_module -static -sub_library -sub_umbrella @gol --twolevel_namespace -umbrella -undefined @gol --unexported_symbols_list -weak_reference_mismatches -whatsloaded} - -@emph{RT Options} -@gccoptlist{-mcall-lib-mul -mfp-arg-in-fpregs -mfp-arg-in-gregs @gol --mfull-fp-blocks -mhc-struct-return -min-line-mul @gol --mminimum-fp-blocks -mnohc-struct-return} +@gccoptlist{-all_load -allowable_client -arch -arch_errors_fatal @gol +-arch_only -bind_at_load -bundle -bundle_loader @gol +-client_name -compatibility_version -current_version @gol +-dependency-file -dylib_file -dylinker_install_name @gol +-dynamic -dynamiclib -exported_symbols_list @gol +-filelist -flat_namespace -force_cpusubtype_ALL @gol +-force_flat_namespace -headerpad_max_install_names @gol +-image_base -init -install_name -keep_private_externs @gol +-multi_module -multiply_defined -multiply_defined_unused @gol +-noall_load -nofixprebinding -nomultidefs -noprebind -noseglinkedit @gol +-pagezero_size -prebind -prebind_all_twolevel_modules @gol +-private_bundle -read_only_relocs -sectalign @gol +-sectobjectsymbols -whyload -seg1addr @gol +-sectcreate -sectobjectsymbols -sectorder @gol +-seg_addr_table -seg_addr_table_filename -seglinkedit @gol +-segprot -segs_read_only_addr -segs_read_write_addr @gol +-single_module -static -sub_library -sub_umbrella @gol +-twolevel_namespace -umbrella -undefined @gol +-unexported_symbols_list -weak_reference_mismatches @gol +-whatsloaded} @emph{MIPS Options} -@gccoptlist{-mabicalls -march=@var{cpu-type} -mtune=@var{cpu=type} @gol --mcpu=@var{cpu-type} -membedded-data -muninit-const-in-rodata @gol --membedded-pic -mfp32 -mfp64 -mfused-madd -mno-fused-madd @gol --mgas -mgp32 -mgp64 @gol --mgpopt -mhalf-pic -mhard-float -mint64 -mips1 @gol --mips2 -mips3 -mips4 -mlong64 -mlong32 -mlong-calls -mmemcpy @gol --mmips-as -mmips-tfile -mno-abicalls @gol --mno-embedded-data -mno-uninit-const-in-rodata @gol --mno-embedded-pic -mno-gpopt -mno-long-calls @gol --mno-memcpy -mno-mips-tfile -mno-rnames -mno-stats @gol --mrnames -msoft-float @gol --m4650 -msingle-float -mmad @gol --mstats -EL -EB -G @var{num} -nocpp @gol --mabi=32 -mabi=n32 -mabi=64 -mabi=eabi @gol --mfix7000 -mno-crt0 -mflush-func=@var{func} -mno-flush-func @gol --mbranch-likely -mno-branch-likely} +@gccoptlist{-EL -EB -march=@var{arch} -mtune=@var{arch} @gol +-mips1 -mips2 -mips3 -mips4 -mips32 -mips32r2 -mips64 @gol +-mips16 -mno-mips16 -mabi=@var{abi} -mabicalls -mno-abicalls @gol +-mxgot -mno-xgot -membedded-pic -mno-embedded-pic @gol +-mgp32 -mgp64 -mfp32 -mfp64 -mhard-float -msoft-float @gol +-msingle-float -mdouble-float -mint64 -mlong64 -mlong32 @gol +-G@var{num} -membedded-data -mno-embedded-data @gol +-muninit-const-in-rodata -mno-uninit-const-in-rodata @gol +-msplit-addresses -mno-split-addresses @gol +-mexplicit-relocs -mno-explicit-relocs @gol +-mrnames -mno-rnames @gol +-mcheck-zero-division -mno-check-zero-division @gol +-mmemcpy -mno-memcpy -mlong-calls -mno-long-calls @gol +-mmad -mno-mad -mfused-madd -mno-fused-madd -nocpp @gol +-mfix-sb1 -mno-fix-sb1 -mflush-func=@var{func} @gol +-mno-flush-func -mbranch-likely -mno-branch-likely} @emph{i386 and x86-64 Options} -@gccoptlist{-mcpu=@var{cpu-type} -march=@var{cpu-type} @gol --mfpmath=@var{unit} -masm=@var{dialect} -mno-fancy-math-387 @gol +@gccoptlist{-mtune=@var{cpu-type} -march=@var{cpu-type} @gol +-mfpmath=@var{unit} @gol +-masm=@var{dialect} -mno-fancy-math-387 @gol -mno-fp-ret-in-387 -msoft-float -msvr3-shlib @gol -mno-wide-multiply -mrtd -malign-double @gol -mpreferred-stack-boundary=@var{num} @gol --mmmx -msse -msse2 -mpni -m3dnow @gol +-mmmx -msse -msse2 -msse3 -m3dnow @gol -mthreads -mno-align-stringops -minline-all-stringops @gol -mpush-args -maccumulate-outgoing-args -m128bit-long-double @gol -m96bit-long-double -mregparm=@var{num} -momit-leaf-frame-pointer @gol --mno-red-zone@gol +-mno-red-zone -mno-tls-direct-seg-refs @gol -mcmodel=@var{code-model} @gol -m32 -m64} @emph{HPPA Options} @gccoptlist{-march=@var{architecture-type} @gol -mbig-switch -mdisable-fpregs -mdisable-indexing @gol --mfast-indirect-calls -mgas -mgnu-ld -mhp-ld @gol --mjump-in-delay -mlinker-opt -mlong-calls @gol +-mfast-indirect-calls -mgas -mgnu-ld -mhp-ld @gol +-mjump-in-delay -mlinker-opt -mlong-calls @gol -mlong-load-store -mno-big-switch -mno-disable-fpregs @gol -mno-disable-indexing -mno-fast-indirect-calls -mno-gas @gol -mno-jump-in-delay -mno-long-load-store @gol @@ -514,6 +532,7 @@ in the following sections. -mbwx -mmax -mfix -mcix @gol -mfloat-vax -mfloat-ieee @gol -mexplicit-relocs -msmall-data -mlarge-data @gol +-msmall-text -mlarge-text @gol -mmemory-latency=@var{time}} @emph{DEC Alpha/VMS Options} @@ -523,7 +542,7 @@ in the following sections. @gccoptlist{-mrelax -mh -ms -mn -mint32 -malign-300} @emph{SH Options} -@gccoptlist{-m1 -m2 -m3 -m3e @gol +@gccoptlist{-m1 -m2 -m2e -m3 -m3e @gol -m4-nofpu -m4-single-only -m4-single -m4 @gol -m5-64media -m5-64media-nofpu @gol -m5-32media -m5-32media-nofpu @gol @@ -553,6 +572,7 @@ in the following sections. -mtda=@var{n} -msda=@var{n} -mzda=@var{n} @gol -mapp-regs -mno-app-regs @gol -mdisable-callt -mno-disable-callt @gol +-mv850e1 @gol -mv850e @gol -mv850 -mbig-switch} @@ -593,9 +613,10 @@ in the following sections. -masm-optimize -mbranch-cost=@var{n} -mcond-exec=@var{n}} @emph{S/390 and zSeries Options} -@gccoptlist{-mhard-float -msoft-float -mbackchain -mno-backchain @gol --msmall-exec -mno-small-exec -mmvcle -mno-mvcle @gol --m64 -m31 -mdebug -mno-debug} +@gccoptlist{-mtune=@var{cpu-type} -march=@var{cpu-type} @gol +-mhard-float -msoft-float -mbackchain -mno-backchain @gol +-msmall-exec -mno-small-exec -mmvcle -mno-mvcle @gol +-m64 -m31 -mdebug -mno-debug -mesa -mzarch -mfused-madd -mno-fused-madd} @emph{CRIS Options} @gccoptlist{-mcpu=@var{cpu} -march=@var{cpu} -mtune=@var{cpu} @gol @@ -603,7 +624,8 @@ in the following sections. -metrax4 -metrax100 -mpdebug -mcc-init -mno-side-effects @gol -mstack-align -mdata-align -mconst-align @gol -m32-bit -m16-bit -m8-bit -mno-prologue-epilogue -mno-gotplt @gol --melf -maout -melinux -mlinux -sim -sim2} +-melf -maout -melinux -mlinux -sim -sim2 @gol +-mmul-bug-workaround -mno-mul-bug-workaround} @emph{PDP-11 Options} @gccoptlist{-mfpu -msoft-float -mac0 -mno-ac0 -m40 -m45 -m10 @gol @@ -617,36 +639,26 @@ in the following sections. @gccoptlist{-msim} @emph{Xtensa Options} -@gccoptlist{-mbig-endian -mlittle-endian @gol --mdensity -mno-density @gol --mmac16 -mno-mac16 @gol --mmul16 -mno-mul16 @gol --mmul32 -mno-mul32 @gol --mnsa -mno-nsa @gol --mminmax -mno-minmax @gol --msext -mno-sext @gol --mbooleans -mno-booleans @gol --mhard-float -msoft-float @gol +@gccoptlist{-mconst16 -mno-const16 @gol -mfused-madd -mno-fused-madd @gol --mserialize-volatile -mno-serialize-volatile @gol -mtext-section-literals -mno-text-section-literals @gol -mtarget-align -mno-target-align @gol -mlongcalls -mno-longcalls} @emph{FRV Options} @gccoptlist{-mgpr-32 -mgpr-64 -mfpr-32 -mfpr-64 @gol --mhard-float -msoft-float -malloc-cc -mfixed-cc @gol --mdword -mno-dword -mdouble -mno-double @gol --mmedia -mno-media -mmuladd -mno-muladd -mlibrary-pic @gol --macc-4 -macc-8 -mpack -mno-pack -mno-eflags @gol --mcond-move -mno-cond-move -mscc -mno-scc @gol --mcond-exec -mno-cond-exec -mvliw-branch -mno-vliw-branch @gol +-mhard-float -msoft-float @gol +-malloc-cc -mfixed-cc -mdword -mno-dword @gol +-mdouble -mno-double @gol +-mmedia -mno-media -mmuladd -mno-muladd @gol +-mlibrary-pic -macc-4 -macc-8 @gol +-mpack -mno-pack -mno-eflags -mcond-move -mno-cond-move @gol +-mscc -mno-scc -mcond-exec -mno-cond-exec @gol +-mvliw-branch -mno-vliw-branch @gol -mmulti-cond-exec -mno-multi-cond-exec -mnested-cond-exec @gol -mno-nested-cond-exec -mtomcat-stats @gol -mcpu=@var{cpu}} - - @item Code Generation Options @xref{Code Gen Options,,Options for Code Generation Conventions}. @gccoptlist{-fcall-saved-@var{reg} -fcall-used-@var{reg} @gol @@ -654,17 +666,16 @@ in the following sections. -fnon-call-exceptions -funwind-tables @gol -fasynchronous-unwind-tables @gol -finhibit-size-directive -finstrument-functions @gol --fno-common -fno-ident -fno-gnu-linker @gol --fpcc-struct-return -fpic -fPIC @gol +-fno-common -fno-ident @gol +-fpcc-struct-return -fpic -fPIC -fpie -fPIE @gol -freg-struct-return -fshared-data -fshort-enums @gol --fshort-double -fshort-wchar -fvolatile @gol --fvolatile-global -fvolatile-static @gol +-fshort-double -fshort-wchar @gol -fverbose-asm -fpack-struct -fstack-check @gol -fstack-limit-register=@var{reg} -fstack-limit-symbol=@var{sym} @gol -fargument-alias -fargument-noalias @gol -fargument-noalias-global -fleading-underscore @gol -ftls-model=@var{model} @gol --ftrapv -fbounds-check} +-ftrapv -fwrapv -fbounds-check} @end table @menu @@ -693,10 +704,12 @@ in the following sections. @section Options Controlling the Kind of Output Compilation can involve up to four stages: preprocessing, compilation -proper, assembly and linking, always in that order. The first three -stages apply to an individual source file, and end by producing an -object file; linking combines all the object files (those newly -compiled, and those specified as input) into an executable file. +proper, assembly and linking, always in that order. GCC is capable of +preprocessing and compiling several files either into several +assembler input files, or into one assembler input file; then each +assembler input file produces an object file, and linking combines all +the object files (those newly compiled, and those specified as input) +into an executable file. @cindex file name suffix For any given input file, the file name suffix determines what kind of @@ -720,18 +733,23 @@ Objective-C source code. Note that you must link with the library Objective-C source code which should not be preprocessed. @item @var{file}.h -C header file (not to be compiled or linked). +C or C++ header file to be turned into a precompiled header. @item @var{file}.cc @itemx @var{file}.cp @itemx @var{file}.cxx @itemx @var{file}.cpp +@itemx @var{file}.CPP @itemx @var{file}.c++ @itemx @var{file}.C C++ source code which must be preprocessed. Note that in @samp{.cxx}, the last two letters must both be literally @samp{x}. Likewise, @samp{.C} refers to a literal capital C@. +@item @var{file}.hh +@itemx @var{file}.H +C++ header file to be turned into a precompiled header. + @item @var{file}.f @itemx @var{file}.for @itemx @var{file}.FOR @@ -793,16 +811,16 @@ Specify explicitly the @var{language} for the following input files (rather than letting the compiler choose a default based on the file name suffix). This option applies to all following input files until the next @option{-x} option. Possible values for @var{language} are: -@example +@smallexample c c-header cpp-output -c++ c++-cpp-output -objective-c objc-cpp-output +c++ c++-header c++-cpp-output +objective-c objective-c-header objc-cpp-output assembler assembler-with-cpp ada f77 f77-cpp-input ratfor java treelang -@end example +@end smallexample @item -x none Turn off any specification of a language, so that subsequent files are @@ -863,9 +881,9 @@ Place output in file @var{file}. This applies regardless to whatever sort of output is being produced, whether it be an executable file, an object file, an assembler file or preprocessed C code. -Since only one output file can be specified, it does not make sense to -use @option{-o} when compiling more than one input file, unless you are -producing an executable file as output. +If you specify @option{-o} when compiling more than one input file, or +you are producing an executable file as output, all the source files +on the command line will be compiled at once. If @option{-o} is not specified, the default is to put an executable file in @file{a.out}, the object file for @file{@var{source}.@var{suffix}} in @@ -897,7 +915,7 @@ Print (on the standard output) a description of the command line options understood by @command{gcc}. If the @option{-v} option is also specified then @option{--help} will also be passed on to the various processes invoked by @command{gcc}, so that they can display the command line options -they accept. If the @option{-W} option is also specified then command +they accept. If the @option{-Wextra} option is also specified then command line options which have no documentation associated with them will also be displayed. @@ -917,22 +935,24 @@ Display the version number and copyrights of the invoked GCC. @cindex suffixes for C++ source @cindex C++ source file suffixes C++ source files conventionally use one of the suffixes @samp{.C}, -@samp{.cc}, @samp{.cpp}, @samp{.c++}, @samp{.cp}, or @samp{.cxx}; +@samp{.cc}, @samp{.cpp}, @samp{.CPP}, @samp{.c++}, @samp{.cp}, or +@samp{.cxx}; C++ header files often use @samp{.hh} or @samp{.H}; and preprocessed C++ files use the suffix @samp{.ii}. GCC recognizes files with these names and compiles them as C++ programs even if you -call the compiler the same way as for compiling C programs (usually with -the name @command{gcc}). +call the compiler the same way as for compiling C programs (usually +with the name @command{gcc}). @findex g++ @findex c++ However, C++ programs often require class libraries as well as a compiler that understands the C++ language---and under some -circumstances, you might want to compile programs from standard input, -or otherwise without a suffix that flags them as C++ programs. -@command{g++} is a program that calls GCC with the default language -set to C++, and automatically specifies linking against the C++ -library. On many systems, @command{g++} is also -installed with the name @command{c++}. +circumstances, you might want to compile programs or header files from +standard input, or otherwise without a suffix that flags them as C++ +programs. You might also like to precompile a C header file with a +@samp{.h} extension to be used in C++ compilations. @command{g++} is a +program that calls GCC with the default language set to C++, and +automatically specifies linking against the C++ library. On many +systems, @command{g++} is also installed with the name @command{c++}. @cindex invoking @command{g++} When you compile C++ programs, you may specify many of the same @@ -1013,14 +1033,14 @@ ISO C90 as modified in amendment 1. @itemx iso9899:1999 @itemx iso9899:199x ISO C99. Note that this standard is not yet fully supported; see -@w{@uref{http://gcc.gnu.org/gcc-3.3/c99status.html}} for more information. The +@w{@uref{http://gcc.gnu.org/gcc-3.4/c99status.html}} for more information. The names @samp{c9x} and @samp{iso9899:199x} are deprecated. @item gnu89 Default, ISO C90 plus GNU extensions (including some C99 features). @item gnu99 -@item gnu9x +@itemx gnu9x ISO C99 plus GNU extensions. When ISO C99 is fully implemented in GCC, this will become the default. The name @samp{gnu9x} is deprecated. @@ -1216,6 +1236,8 @@ write into string constants. Writing into string constants is a very bad idea; ``constants'' should be constant. + +This option is deprecated. @end table @node C++ Dialect Options @@ -1229,9 +1251,9 @@ for C++ programs; but you can also use most of the GNU compiler options regardless of what language your program is in. For example, you might compile a file @code{firstClass.C} like this: -@example +@smallexample g++ -g -frepo -O -c firstClass.C -@end example +@end smallexample @noindent In this example, only @option{-frepo} is an option meant @@ -1244,13 +1266,14 @@ Here is a list of options that are @emph{only} for compiling C++ programs: @item -fabi-version=@var{n} @opindex fabi-version -Use version @var{n} of the C++ ABI. Version 1 is the version of the C++ -ABI that first appeared in G++ 3.2. Version 0 will always be the -version that conforms most closely to the C++ ABI specification. -Therefore, the ABI obtained using version 0 will change as ABI bugs are -fixed. +Use version @var{n} of the C++ ABI. Version 2 is the version of the +C++ ABI that first appeared in G++ 3.4. Version 1 is the version of +the C++ ABI that first appeared in G++ 3.2. Version 0 will always be +the version that conforms most closely to the C++ ABI specification. +Therefore, the ABI obtained using version 0 will change as ABI bugs +are fixed. -The default is version 1. +The default is version 2. @item -fno-access-control @opindex fno-access-control @@ -1293,14 +1316,6 @@ This option might be removed in a future release of G++. For maximum portability, you should structure your code so that it works with string constants that have type @code{const char *}. -@item -fdollars-in-identifiers -@opindex fdollars-in-identifiers -Accept @samp{$} in identifiers. You can also explicitly prohibit use of -@samp{$} with the option @option{-fno-dollars-in-identifiers}. (GNU C allows -@samp{$} by default on most target systems, but there are a few exceptions.) -Traditional C allowed the character @samp{$} to form part of -identifiers. However, ISO C and C++ forbid @samp{$} in identifiers. - @item -fno-elide-constructors @opindex fno-elide-constructors The C++ standard allows an implementation to omit creating a temporary @@ -1315,24 +1330,6 @@ option violates the C++ standard, but may be useful for reducing code size in production builds, much like defining @samp{NDEBUG}. The compiler will still optimize based on the exception specifications. -@item -fexternal-templates -@opindex fexternal-templates - -Cause @samp{#pragma interface} and @samp{implementation} to apply to -template instantiation; template instances are emitted or not according -to the location of the template definition. @xref{Template -Instantiation}, for more information. - -This option is deprecated. - -@item -falt-external-templates -@opindex falt-external-templates -Similar to @option{-fexternal-templates}, but template instances are -emitted or not according to the place where they are first instantiated. -@xref{Template Instantiation}, for more information. - -This option is deprecated. - @item -ffor-scope @itemx -fno-for-scope @opindex ffor-scope @@ -1437,17 +1434,6 @@ This option is required for fully standards-compliant handling of static destructors, but will only work if your C library supports @code{__cxa_atexit}. -@item -fvtable-gc -@opindex fvtable-gc -Emit special relocations for vtables and virtual function references -so that the linker can identify unused virtual functions and zero out -vtable slots that refer to them. This is most useful with -@option{-ffunction-sections} and @option{-Wl,--gc-sections}, in order to -also discard the functions themselves. - -This optimization requires GNU as and GNU ld. Not all systems support -this option. @option{-Wl,--gc-sections} is ignored without @option{-static}. - @item -fno-weak @opindex fno-weak Do not use weak symbol support, even if it is provided by the linker. @@ -1478,7 +1464,7 @@ inlined by default. @opindex Wabi Warn when G++ generates code that is probably not compatible with the vendor-neutral C++ ABI. Although an effort has been made to warn about -all such cases, there are probably some cases that are not warned about, +all such cases, there are probably some cases that are not warned about, even though G++ is generating incompatible code. There may also be cases where warnings are emitted even though the code that is generated will be compatible. @@ -1502,7 +1488,7 @@ struct B : public A @{ int f2 : 1; @}; @noindent In this case, G++ will place @code{B::f2} into the same byte -as@code{A::f1}; other compilers will not. You can avoid this problem +as@code{A::f1}; other compilers will not. You can avoid this problem by explicitly padding @code{A} so that its size is a multiple of the byte size on your platform; that will cause G++ and other compilers to layout @code{B} identically. @@ -1539,7 +1525,7 @@ union too small by the number of bits in an @code{int}. @item Empty classes can be placed at incorrect offsets. For example: - + @smallexample struct A @{@}; @@ -1577,7 +1563,7 @@ Instantiations of these templates may be mangled incorrectly. @opindex Wctor-dtor-privacy Warn when a class seems unusable because all the constructors or destructors in that class are private, and it has neither friends nor -public static member functions. This warning is enabled by default. +public static member functions. @item -Wnon-virtual-dtor @r{(C++ only)} @opindex Wnon-virtual-dtor @@ -1632,7 +1618,7 @@ Item 23: Don't try to return a reference when you must return an object. @end itemize -Also warn about violations of the following style guidelines from +Also warn about violations of the following style guidelines from Scott Meyers' @cite{More Effective C++} book: @itemize @bullet @@ -1711,7 +1697,7 @@ to a plain pointer. @item -Wsign-promo @r{(C++ only)} @opindex Wsign-promo Warn when overload resolution chooses a promotion from unsigned or -enumeral type to a signed type, over a conversion to an unsigned type of +enumerated type to a signed type, over a conversion to an unsigned type of the same size. Previous versions of G++ would try to preserve unsignedness, but the standard mandates the current behavior. @@ -1745,14 +1731,17 @@ In this example, G++ will synthesize a default @samp{A& operator = @cindex compiler options, Objective-C @cindex Objective-C options, command line @cindex options, Objective-C +(NOTE: This manual does not describe the Objective-C language itself. See +@w{@uref{http://gcc.gnu.org/readings.html}} for references.) + This section describes the command-line options that are only meaningful for Objective-C programs, but you can also use most of the GNU compiler options regardless of what language your program is in. For example, you might compile a file @code{some_class.m} like this: -@example +@smallexample gcc -g -fgnu-runtime -O -c some_class.m -@end example +@end smallexample @noindent In this example, @option{-fgnu-runtime} is an option meant only for @@ -1767,7 +1756,11 @@ programs: @opindex fconstant-string-class Use @var{class-name} as the name of the class to instantiate for each literal string specified with the syntax @code{@@"@dots{}"}. The default -class name is @code{NXConstantString}. +class name is @code{NXConstantString} if the GNU runtime is being used, and +@code{NSConstantString} if the NeXT runtime is being used (see below). The +@option{-fconstant-cfstrings} option, if also present, will override the +@option{-fconstant-string-class} setting and cause @code{@@"@dots{}"} literals +to be laid out as constant CoreFoundation strings. @item -fgnu-runtime @opindex fgnu-runtime @@ -1781,6 +1774,127 @@ for NeXT-based systems, including Darwin and Mac OS X@. The macro @code{__NEXT_RUNTIME__} is predefined if (and only if) this option is used. +@item -fno-nil-receivers +@opindex fno-nil-receivers +Assume that all Objective-C message dispatches (e.g., +@code{[receiver message:arg]}) in this translation unit ensure that the receiver +is not @code{nil}. This allows for more efficient entry points in the runtime to be +used. Currently, this option is only available in conjunction with +the NeXT runtime on Mac OS X 10.3 and later. + +@item -fobjc-exceptions +@opindex fobjc-exceptions +Enable syntactic support for structured exception handling in Objective-C, +similar to what is offered by C++ and Java. Currently, this option is only +available in conjunction with the NeXT runtime on Mac OS X 10.3 and later. + +@smallexample + @@try @{ + @dots{} + @@throw expr; + @dots{} + @} + @@catch (AnObjCClass *exc) @{ + @dots{} + @@throw expr; + @dots{} + @@throw; + @dots{} + @} + @@catch (AnotherClass *exc) @{ + @dots{} + @} + @@catch (id allOthers) @{ + @dots{} + @} + @@finally @{ + @dots{} + @@throw expr; + @dots{} + @} +@end smallexample + +The @code{@@throw} statement may appear anywhere in an Objective-C or +Objective-C++ program; when used inside of a @code{@@catch} block, the +@code{@@throw} may appear without an argument (as shown above), in which case +the object caught by the @code{@@catch} will be rethrown. + +Note that only (pointers to) Objective-C objects may be thrown and +caught using this scheme. When an object is thrown, it will be caught +by the nearest @code{@@catch} clause capable of handling objects of that type, +analogously to how @code{catch} blocks work in C++ and Java. A +@code{@@catch(id @dots{})} clause (as shown above) may also be provided to catch +any and all Objective-C exceptions not caught by previous @code{@@catch} +clauses (if any). + +The @code{@@finally} clause, if present, will be executed upon exit from the +immediately preceding @code{@@try @dots{} @@catch} section. This will happen +regardless of whether any exceptions are thrown, caught or rethrown +inside the @code{@@try @dots{} @@catch} section, analogously to the behavior +of the @code{finally} clause in Java. + +There are several caveats to using the new exception mechanism: + +@itemize @bullet +@item +Although currently designed to be binary compatible with @code{NS_HANDLER}-style +idioms provided by the @code{NSException} class, the new +exceptions can only be used on Mac OS X 10.3 (Panther) and later +systems, due to additional functionality needed in the (NeXT) Objective-C +runtime. + +@item +As mentioned above, the new exceptions do not support handling +types other than Objective-C objects. Furthermore, when used from +Objective-C++, the Objective-C exception model does not interoperate with C++ +exceptions at this time. This means you cannot @code{@@throw} an exception +from Objective-C and @code{catch} it in C++, or vice versa +(i.e., @code{throw @dots{} @@catch}). +@end itemize + +The @option{-fobjc-exceptions} switch also enables the use of synchronization +blocks for thread-safe execution: + +@smallexample + @@synchronized (ObjCClass *guard) @{ + @dots{} + @} +@end smallexample + +Upon entering the @code{@@synchronized} block, a thread of execution shall +first check whether a lock has been placed on the corresponding @code{guard} +object by another thread. If it has, the current thread shall wait until +the other thread relinquishes its lock. Once @code{guard} becomes available, +the current thread will place its own lock on it, execute the code contained in +the @code{@@synchronized} block, and finally relinquish the lock (thereby +making @code{guard} available to other threads). + +Unlike Java, Objective-C does not allow for entire methods to be marked +@code{@@synchronized}. Note that throwing exceptions out of +@code{@@synchronized} blocks is allowed, and will cause the guarding object +to be unlocked properly. + +@item -freplace-objc-classes +@opindex freplace-objc-classes +Emit a special marker instructing @command{ld(1)} not to statically link in +the resulting object file, and allow @command{dyld(1)} to load it in at +run time instead. This is used in conjunction with the Fix-and-Continue +debugging mode, where the object file in question may be recompiled and +dynamically reloaded in the course of program execution, without the need +to restart the program itself. Currently, Fix-and-Continue functionality +is only available in conjunction with the NeXT runtime on Mac OS X 10.3 +and later. + +@item -fzero-link +@opindex fzero-link +When compiling for the NeXT runtime, the compiler ordinarily replaces calls +to @code{objc_getClass("@dots{}")} (when the name of the class is known at +compile time) with static class references that get initialized at load time, +which improves run-time performance. Specifying the @option{-fzero-link} flag +suppresses this behavior and causes calls to @code{objc_getClass("@dots{}")} +to be retained. This is useful in Zero-Link debugging mode, since it allows +for individual class implementations to be modified during program execution. + @item -gen-decls @opindex gen-decls Dump interface declarations for all classes seen in the source file to a @@ -1813,7 +1927,7 @@ being used. @opindex Wundeclared-selector Warn if a @code{@@selector(@dots{})} expression referring to an undeclared selector is found. A selector is considered undeclared if no -method with that name has been declared before the +method with that name has been declared before the @code{@@selector(@dots{})} expression, either explicitly in an @code{@@interface} or @code{@@protocol} declaration, or implicitly in an @code{@@implementation} section. This option always performs its @@ -1822,8 +1936,10 @@ while @code{-Wselector} only performs its checks in the final stage of compilation. This also enforces the coding style convention that methods and selectors must be declared before being used. -@c not documented because only avail via -Wp -@c @item -print-objc-runtime-info +@item -print-objc-runtime-info +@opindex print-objc-runtime-info +Generate C header describing the largest structure that is passed by +value, if any. @end table @@ -1985,14 +2101,14 @@ Since @option{-Wformat} also checks for null format arguments for several functions, @option{-Wformat} also implies @option{-Wnonnull}. @option{-Wformat} is included in @option{-Wall}. For more control over some -aspects of format checking, the options @option{-Wno-format-y2k}, +aspects of format checking, the options @option{-Wformat-y2k}, @option{-Wno-format-extra-args}, @option{-Wno-format-zero-length}, @option{-Wformat-nonliteral}, @option{-Wformat-security}, and @option{-Wformat=2} are available, but are not included in @option{-Wall}. -@item -Wno-format-y2k -@opindex Wno-format-y2k -If @option{-Wformat} is specified, do not warn about @code{strftime} +@item -Wformat-y2k +@opindex Wformat-y2k +If @option{-Wformat} is specified, also warn about @code{strftime} formats which may yield only a two-digit year. @item -Wno-format-extra-args @@ -2036,16 +2152,34 @@ included in @option{-Wformat-nonliteral}.) @opindex Wformat=2 Enable @option{-Wformat} plus format checks not included in @option{-Wformat}. Currently equivalent to @samp{-Wformat --Wformat-nonliteral -Wformat-security}. +-Wformat-nonliteral -Wformat-security -Wformat-y2k}. @item -Wnonnull @opindex Wnonnull -Enable warning about passing a null pointer for arguments marked as +Warn about passing a null pointer for arguments marked as requiring a non-null value by the @code{nonnull} function attribute. @option{-Wnonnull} is included in @option{-Wall} and @option{-Wformat}. It can be disabled with the @option{-Wno-nonnull} option. +@item -Winit-self @r{(C, C++, and Objective-C only)} +@opindex Winit-self +Warn about uninitialized variables which are initialized with themselves. +Note this option can only be used with the @option{-Wuninitialized} option, +which in turn only works with @option{-O1} and above. + +For example, GCC will warn about @code{i} being uninitialized in the +following snippet only when @option{-Winit-self} has been specified: +@smallexample +@group +int f() +@{ + int i = i; + return i; +@} +@end group +@end smallexample + @item -Wimplicit-int @opindex Wimplicit-int Warn when a declaration does not specify a type. @@ -2167,7 +2301,7 @@ future implementation may also work for C++ programs. The C standard is worded confusingly, therefore there is some debate over the precise meaning of the sequence point rules in subtle cases. Links to discussions of the problem, including proposed formal -definitions, may be found on our readings page, at +definitions, may be found on the GCC readings page, at @w{@uref{http://gcc.gnu.org/readings.html}}. @item -Wreturn-type @@ -2182,7 +2316,7 @@ exceptions are @samp{main} and functions defined in system headers. @item -Wswitch @opindex Wswitch -Warn whenever a @code{switch} statement has an index of enumeral type +Warn whenever a @code{switch} statement has an index of enumerated type and lacks a @code{case} for one or more of the named codes of that enumeration. (The presence of a @code{default} label prevents this warning.) @code{case} labels outside the enumeration range also @@ -2195,7 +2329,7 @@ case. @item -Wswitch-enum @opindex Wswitch-enum -Warn whenever a @code{switch} statement has an index of enumeral type +Warn whenever a @code{switch} statement has an index of enumerated type and lacks a @code{case} for one or more of the named codes of that enumeration. @code{case} labels outside the enumeration range also provoke warnings when this option is used. @@ -2243,8 +2377,8 @@ To suppress this warning cast the expression to @samp{void}. All the above @option{-Wunused} options combined. In order to get a warning about an unused function parameter, you must -either specify @samp{-W -Wunused} or separately specify -@option{-Wunused-parameter}. +either specify @samp{-Wextra -Wunused} (note that @samp{-Wall} implies +@samp{-Wunused}), or separately specify @option{-Wunused-parameter}. @item -Wuninitialized @opindex Wuninitialized @@ -2256,6 +2390,9 @@ because they require data flow information that is computed only when optimizing. If you don't specify @option{-O}, you simply won't get these warnings. +If you want to warn about code which uses the uninitialized value of the +variable in its own initializer, use the @option{-Winit-self} option. + These warnings occur only for variables that are candidates for register allocation. Therefore, they do not occur for a variable that is declared @code{volatile}, or whose address is taken, or whose size @@ -2357,9 +2494,12 @@ in some cases, and there is no simple way to modify the code to suppress the warning. @table @gcctabopt -@item -W +@item -Wextra @opindex W -Print extra warning messages for these events: +@opindex Wextra +(This option used to be called @option{-W}. The older name is still +supported, but the newer name is more descriptive.) Print extra warning +messages for these events: @itemize @bullet @item @@ -2414,17 +2554,6 @@ incorrect result when the signed value is converted to unsigned. (But don't warn if @option{-Wno-sign-compare} is also specified.) @item -An aggregate has a partly bracketed initializer. -For example, the following code would evoke such a warning, -because braces are missing around the initializer for @code{x.h}: - -@smallexample -struct s @{ int f, g; @}; -struct t @{ struct s h; int i; @}; -struct t x = @{ 1, 2, 3 @}; -@end smallexample - -@item An aggregate has an initializer which does not initialize all members. For example, the following code would cause such a warning, because @code{x.h} would be implicitly initialized to zero: @@ -2433,6 +2562,47 @@ For example, the following code would cause such a warning, because struct s @{ int f, g, h; @}; struct s x = @{ 3, 4 @}; @end smallexample + +@item +A function parameter is declared without a type specifier in K&R-style +functions: + +@smallexample +void foo(bar) @{ @} +@end smallexample + +@item +An empty body occurs in an @samp{if} or @samp{else} statement. + +@item +A pointer is compared against integer zero with @samp{<}, @samp{<=}, +@samp{>}, or @samp{>=}. + +@item +A variable might be changed by @samp{longjmp} or @samp{vfork}. + +@item +Any of several floating-point events that often indicate errors, such as +overflow, underflow, loss of precision, etc. + +@item @r{(C++ only)} +An enumerator and a non-enumerator both appear in a conditional expression. + +@item @r{(C++ only)} +A non-static reference or non-static @samp{const} member appears in a +class without constructors. + +@item @r{(C++ only)} +Ambiguous virtual bases. + +@item @r{(C++ only)} +Subscripting an array which has been declared @samp{register}. + +@item @r{(C++ only)} +Taking the address of a variable which has been declared @samp{register}. + +@item @r{(C++ only)} +A base class is not initialized in a derived class' copy constructor. @end itemize @item -Wno-div-by-zero @@ -2505,7 +2675,7 @@ constant suffixes. (Traditional C does support the @samp{L} suffix on integer constants.) Note, these suffixes appear in macros defined in the system headers of most modern systems, e.g.@: the @samp{_MIN}/@samp{_MAX} macros in @code{<limits.h>}. Use of these macros in user code might normally lead to spurious -warnings, however gcc's integrated preprocessor has enough context to +warnings, however GCC's integrated preprocessor has enough context to avoid warning in these cases. @item @@ -2554,10 +2724,17 @@ Use of ISO C style function definitions. This warning intentionally is because these ISO C features will appear in your code when using libiberty's traditional C compatibility macros, @code{PARAMS} and @code{VPARAMS}. This warning is also bypassed for nested functions -because that feature is already a gcc extension and thus not relevant to +because that feature is already a GCC extension and thus not relevant to traditional C compatibility. @end itemize +@item -Wdeclaration-after-statement @r{(C only)} +@opindex Wdeclaration-after-statement +Warn when a declaration is found after a statement in a block. This +construct, known from C++, was introduced with ISO C99 and is by default +allowed in GCC@. It is not supported by ISO C90 and was not supported by +GCC versions before GCC 3.0. @xref{Mixed Declarations}. + @item -Wundef @opindex Wundef Warn if an undefined identifier is evaluated in an @samp{#if} directive. @@ -2633,8 +2810,8 @@ casts like @code{(unsigned) -1}. @cindex signed and unsigned values, comparison warning Warn when a comparison between signed and unsigned values could produce an incorrect result when the signed value is converted to unsigned. -This warning is enabled by @option{-W}, and by @option{-Wall} -in C++ only. +This warning is also enabled by @option{-Wextra}; to get the other warnings +of @option{-Wextra} without this warning, use @samp{-Wextra -Wno-sign-compare}. @item -Waggregate-return @opindex Waggregate-return @@ -2649,6 +2826,11 @@ argument types. (An old-style function definition is permitted without a warning if preceded by a declaration which specifies the argument types.) +@item -Wold-style-definition @r{(C only)} +@opindex Wold-style-definition +Warn if an old-style function definition is used. A warning is given +even if there is a previous prototype. + @item -Wmissing-prototypes @r{(C only)} @opindex Wmissing-prototypes Warn if a global function is defined without a previous prototype @@ -2762,7 +2944,7 @@ code is to provide behavior which is selectable at compile-time. @opindex Winline Warn if a function can not be inlined and it was declared as inline. Even with this option, the compiler will not warn about failures to -inline functions declared in system headers. +inline functions declared in system headers. The compiler uses a variety of heuristics to determine whether or not to inline a function. For example, the compiler takes into account @@ -2771,6 +2953,26 @@ that has already been done in the current function. Therefore, seemingly insignificant changes in the source program can cause the warnings produced by @option{-Winline} to appear or disappear. +@item -Wno-invalid-offsetof @r{(C++ only)} +@opindex Wno-invalid-offsetof +Suppress warnings from applying the @samp{offsetof} macro to a non-POD +type. According to the 1998 ISO C++ standard, applying @samp{offsetof} +to a non-POD type is undefined. In existing C++ implementations, +however, @samp{offsetof} typically gives meaningful results even when +applied to certain kinds of non-POD types. (Such as a simple +@samp{struct} that fails to be a POD type only by virtue of having a +constructor.) This flag is for users who are aware that they are +writing nonportable code and who have deliberately chosen to ignore the +warning about it. + +The restrictions on @samp{offsetof} may be relaxed in a future version +of the C++ standard. + +@item -Winvalid-pch +@opindex Winvalid-pch +Warn if a precompiled header (@pxref{Precompiled Headers}) is found in +the search path but can't be used. + @item -Wlong-long @opindex Wlong-long @opindex Wno-long-long @@ -2814,8 +3016,7 @@ makes debugging work better in GDB but will probably make other debuggers crash or refuse to read the program. If you want to control for certain whether to generate the extra information, use @option{-gstabs+}, @option{-gstabs}, -@option{-gxcoff+}, @option{-gxcoff}, @option{-gdwarf-1+}, @option{-gdwarf-1}, -or @option{-gvms} (see below). +@option{-gxcoff+}, @option{-gxcoff}, or @option{-gvms} (see below). Unlike most other C compilers, GCC allows you to use @option{-g} with @option{-O}. The shortcuts taken by optimized code may occasionally @@ -2846,6 +3047,11 @@ systems. On MIPS, Alpha and System V Release 4 systems this option produces stabs debugging output which is not understood by DBX or SDB@. On System V Release 4 systems this option requires the GNU assembler. +@item -feliminate-unused-debug-symbols +@opindex feliminate-unused-debug-symbols +Produce debugging information in stabs format (if that is supported), +for only symbols that are actually used. + @item -gstabs+ @opindex gstabs+ Produce debugging information in stabs format (if that is supported), @@ -2872,23 +3078,6 @@ use of these extensions is likely to make other debuggers crash or refuse to read the program, and may cause assemblers other than the GNU assembler (GAS) to fail with an error. -@item -gdwarf -@opindex gdwarf -Produce debugging information in DWARF version 1 format (if that is -supported). This is the format used by SDB on most System V Release 4 -systems. - -This option is deprecated. - -@item -gdwarf+ -@opindex gdwarf+ -Produce debugging information in DWARF version 1 format (if that is -supported), using GNU extensions understood only by the GNU debugger -(GDB)@. The use of these extensions is likely to make other debuggers -crash or refuse to read the program. - -This option is deprecated. - @item -gdwarf-2 @opindex gdwarf-2 Produce debugging information in DWARF version 2 format (if that is @@ -2918,9 +3107,9 @@ present in the program. Some debuggers support macro expansion when you use @option{-g3}. Note that in order to avoid confusion between DWARF1 debug level 2, -and DWARF2, neither @option{-gdwarf} nor @option{-gdwarf-2} accept -a concatenated debug level. Instead use an additional @option{-g@var{level}} -option to change the debug level for DWARF1 or DWARF2. +and DWARF2 @option{-gdwarf-2} does not accept a concatenated debug +level. Instead use an additional @option{-g@var{level}} option to +change the debug level for DWARF2. @item -feliminate-dwarf2-dups @opindex feliminate-dwarf2-dups @@ -2961,27 +3150,51 @@ allocation when it finishes. @item -fprofile-arcs @opindex fprofile-arcs -Instrument @dfn{arcs} during compilation to generate coverage data or -for profile-directed block ordering. During execution the program -records how many times each branch is executed and how many times it is -taken. When the compiled program exits it saves this data to a file -called @file{@var{auxname}.da} for each source file. @var{auxname} is -generated from the name of the output file, if explicitly specified and -it is not the final executable, otherwise it is the basename of the -source file. In both cases any suffix is removed (e.g. @file{foo.da} -for input file @file{dir/foo.c}, or @file{dir/foo.da} for output file -specified as @option{-o dir/foo.o}). - -For profile-directed block ordering, compile the program with -@option{-fprofile-arcs} plus optimization and code generation options, -generate the arc profile information by running the program on a -selected workload, and then compile the program again with the same -optimization and code generation options plus +Add code so that program flow @dfn{arcs} are instrumented. During +execution the program records how many times each branch and call is +executed and how many times it is taken or returns. When the compiled +program exits it saves this data to a file called +@file{@var{auxname}.gcda} for each source file. The data may be used for +profile-directed optimizations (@option{-fbranch-probabilities}), or for +test coverage analysis (@option{-ftest-coverage}). Each object file's +@var{auxname} is generated from the name of the output file, if +explicitly specified and it is not the final executable, otherwise it is +the basename of the source file. In both cases any suffix is removed +(e.g. @file{foo.gcda} for input file @file{dir/foo.c}, or +@file{dir/foo.gcda} for output file specified as @option{-o dir/foo.o}). + +@itemize + +@item +Compile the source files with @option{-fprofile-arcs} plus optimization +and code generation options. For test coverage analysis, use the +additional @option{-ftest-coverage} option. You do not need to profile +every source file in a program. + +@item +Link your object files with @option{-lgcov} or @option{-fprofile-arcs} +(the latter implies the former). + +@item +Run the program on a representative workload to generate the arc profile +information. This may be repeated any number of times. You can run +concurrent instances of your program, and provided that the file system +supports locking, the data files will be correctly updated. Also +@code{fork} calls are detected and correctly handled (double counting +will not happen). + +@item +For profile-directed optimizations, compile the source files again with +the same optimization and code generation options plus @option{-fbranch-probabilities} (@pxref{Optimize Options,,Options that Control Optimization}). -The other use of @option{-fprofile-arcs} is for use with @command{gcov}, -when it is used with the @option{-ftest-coverage} option. +@item +For test coverage analysis, use @command{gcov} to produce human readable +information from the @file{.gcno} and @file{.gcda} files. Refer to the +@command{gcov} documentation for further information. + +@end itemize With @option{-fprofile-arcs}, for each function of your program GCC creates a program flow graph, then finds a spanning tree for the graph. @@ -2994,34 +3207,13 @@ block must be created to hold the instrumentation code. @need 2000 @item -ftest-coverage @opindex ftest-coverage -Create data files for the @command{gcov} code-coverage utility -(@pxref{Gcov,, @command{gcov}---a Test Coverage Program}). See -@option{-fprofile-arcs} option above for a description of @var{auxname}. - -@table @gcctabopt -@item @var{auxname}.bb -A mapping from basic blocks to line numbers, which @command{gcov} uses to -associate basic block execution counts with line numbers. - -@item @var{auxname}.bbg -A list of all arcs in the program flow graph. This allows @command{gcov} -to reconstruct the program flow graph, so that it can compute all basic -block and arc execution counts from the information in the -@file{@var{auxname}.da} file. -@end table - -Use @option{-ftest-coverage} with @option{-fprofile-arcs}; the latter -option adds instrumentation to the program, which then writes -execution counts to another data file: - -@table @gcctabopt -@item @var{auxname}.da -Runtime arc execution counts, used in conjunction with the arc -information in the file @file{@var{auxname}.bbg}. -@end table - -Coverage data will map better to the source files if -@option{-ftest-coverage} is used without optimization. +Produce a notes file that the @command{gcov} code-coverage utility +(@pxref{Gcov,, @command{gcov}---a Test Coverage Program}) can use to +show program coverage. Each source file's note file is called +@file{@var{auxname}.gcno}. Refer to the @option{-fprofile-arcs} option +above for a description of @var{auxname} and instructions on how to +generate test coverage data. Coverage data will match the source files +more closely, if you do not optimize. @item -d@var{letters} @opindex d @@ -3031,7 +3223,7 @@ for most of the dumps are made by appending a pass number and a word to the @var{dumpname}. @var{dumpname} is generated from the name of the output file, if explicitly specified and it is not an executable, otherwise it is the basename of the source file. In both cases any -suffix is removed (e.g. @file{foo.00.rtl} or @file{foo.01.sibling}). +suffix is removed (e.g. @file{foo.01.rtl} or @file{foo.02.sibling}). Here are the possible letters for use in @var{letters}, and their meanings: @@ -3041,113 +3233,119 @@ meanings: Annotate the assembler output with miscellaneous debugging information. @item b @opindex db -Dump after computing branch probabilities, to @file{@var{file}.14.bp}. +Dump after computing branch probabilities, to @file{@var{file}.12.bp}. @item B @opindex dB -Dump after block reordering, to @file{@var{file}.32.bbro}. +Dump after block reordering, to @file{@var{file}.31.bbro}. @item c @opindex dc -Dump after instruction combination, to the file @file{@var{file}.19.combine}. +Dump after instruction combination, to the file @file{@var{file}.20.combine}. @item C @opindex dC -Dump after the first if conversion, to the file @file{@var{file}.15.ce1}. +Dump after the first if conversion, to the file @file{@var{file}.14.ce1}. +Also dump after the second if conversion, to the file @file{@var{file}.21.ce2}. @item d @opindex dd -Dump after delayed branch scheduling, to @file{@var{file}.34.dbr}. +Dump after branch target load optimization, to to @file{@var{file}.32.btl}. +Also dump after delayed branch scheduling, to @file{@var{file}.36.dbr}. @item D @opindex dD Dump all macro definitions, at the end of preprocessing, in addition to normal output. -@item e -@opindex de -Dump after SSA optimizations, to @file{@var{file}.04.ssa} and -@file{@var{file}.07.ussa}. @item E @opindex dE -Dump after the second if conversion, to @file{@var{file}.29.ce3}. +Dump after the third if conversion, to @file{@var{file}.30.ce3}. @item f @opindex df -Dump after control and data flow analysis, to @file{@var{file}.14.cfg}. -Also dump after life analysis, to @file{@var{file}.18.life}. +Dump after control and data flow analysis, to @file{@var{file}.11.cfg}. +Also dump after life analysis, to @file{@var{file}.19.life}. @item F @opindex dF -Dump after purging @code{ADDRESSOF} codes, to @file{@var{file}.10.addressof}. +Dump after purging @code{ADDRESSOF} codes, to @file{@var{file}.07.addressof}. @item g @opindex dg -Dump after global register allocation, to @file{@var{file}.24.greg}. +Dump after global register allocation, to @file{@var{file}.25.greg}. @item G @opindex dG -Dump after GCSE, to @file{@var{file}.11.gcse}. +Dump after GCSE, to @file{@var{file}.08.gcse}. +Also dump after jump bypassing and control flow optimizations, to +@file{@var{file}.10.bypass}. @item h @opindex dh -Dump after finalization of EH handling code, to @file{@var{file}.02.eh}. +Dump after finalization of EH handling code, to @file{@var{file}.03.eh}. @item i @opindex di -Dump after sibling call optimizations, to @file{@var{file}.01.sibling}. +Dump after sibling call optimizations, to @file{@var{file}.02.sibling}. @item j @opindex dj -Dump after the first jump optimization, to @file{@var{file}.03.jump}. +Dump after the first jump optimization, to @file{@var{file}.04.jump}. @item k @opindex dk -Dump after conversion from registers to stack, to @file{@var{file}.31.stack}. +Dump after conversion from registers to stack, to @file{@var{file}.34.stack}. @item l @opindex dl -Dump after local register allocation, to @file{@var{file}.23.lreg}. +Dump after local register allocation, to @file{@var{file}.24.lreg}. @item L @opindex dL -Dump after loop optimization, to @file{@var{file}.12.loop}. +Dump after loop optimization passes, to @file{@var{file}.09.loop} and +@file{@var{file}.16.loop2}. @item M @opindex dM Dump after performing the machine dependent reorganization pass, to -@file{@var{file}.33.mach}. +@file{@var{file}.35.mach}. @item n @opindex dn -Dump after register renumbering, to @file{@var{file}.28.rnreg}. +Dump after register renumbering, to @file{@var{file}.29.rnreg}. @item N @opindex dN -Dump after the register move pass, to @file{@var{file}.21.regmove}. +Dump after the register move pass, to @file{@var{file}.22.regmove}. @item o @opindex do -Dump after post-reload optimizations, to @file{@var{file}.25.postreload}. +Dump after post-reload optimizations, to @file{@var{file}.26.postreload}. @item r @opindex dr -Dump after RTL generation, to @file{@var{file}.00.rtl}. +Dump after RTL generation, to @file{@var{file}.01.rtl}. @item R @opindex dR -Dump after the second scheduling pass, to @file{@var{file}.30.sched2}. +Dump after the second scheduling pass, to @file{@var{file}.33.sched2}. @item s @opindex ds Dump after CSE (including the jump optimization that sometimes follows -CSE), to @file{@var{file}.09.cse}. +CSE), to @file{@var{file}.06.cse}. @item S @opindex dS -Dump after the first scheduling pass, to @file{@var{file}.22.sched}. +Dump after the first scheduling pass, to @file{@var{file}.23.sched}. @item t @opindex dt Dump after the second CSE pass (including the jump optimization that -sometimes follows CSE), to @file{@var{file}.17.cse2}. +sometimes follows CSE), to @file{@var{file}.18.cse2}. @item T @opindex dT -Dump after running tracer, to @file{@var{file}.16.tracer}. +Dump after running tracer, to @file{@var{file}.15.tracer}. @item u @opindex du -Dump after null pointer elimination pass to @file{@var{file}.08.null}. +Dump after null pointer elimination pass to @file{@var{file}.05.null}. +@item U +@opindex dU +Dump callgraph and unit-at-a-time optimization @file{@var{file}.00.unit}. +@item V +@opindex dV +Dump after the value profile transformations, to @file{@var{file}.13.vpt}. @item w @opindex dw -Dump after the second flow pass, to @file{@var{file}.26.flow2}. -@item W -@opindex dW -Dump after SSA conditional constant propagation, to -@file{@var{file}.05.ssaccp}. -@item X -@opindex dX -Dump after SSA dead code elimination, to @file{@var{file}.06.ssadce}. +Dump after the second flow pass, to @file{@var{file}.27.flow2}. @item z @opindex dz -Dump after the peephole pass, to @file{@var{file}.27.peephole2}. +Dump after the peephole pass, to @file{@var{file}.28.peephole2}. +@item Z +@opindex dZ +Dump after constructing the web, to @file{@var{file}.17.web}. @item a @opindex da Produce all the dumps listed above. +@item H +@opindex dH +Produce a core dump whenever an error occurs. @item m @opindex dm Print statistics on memory usage, at the end of the run, to @@ -3164,7 +3362,7 @@ Also turns on @option{-dp} annotation. @item v @opindex dv For each of the other indicated dump files (except for -@file{@var{file}.00.rtl}), dump a representation of the control flow graph +@file{@var{file}.01.rtl}), dump a representation of the control flow graph suitable for viewing with VCG to @file{@var{file}.@var{pass}.vcg}. @item x @opindex dx @@ -3237,8 +3435,11 @@ Dump after function inlining, to @file{@var{file}.inlined}. @item -frandom-seed=@var{string} @opindex frandom-string This option provides a seed that GCC uses when it would otherwise use -random numbers. At present, this is used to generate certain symbol names -that have to be different in every compiled file. +random numbers. It is used to generate certain symbol names +that have to be different in every compiled file. It is also used to +place unique stamps in coverage data files and the object files that +produce them. You can use the @option{-frandom-seed} option to produce +reproducibly identical object files. The @var{string} should be different for every file you compile. @@ -3316,19 +3517,19 @@ Same as @option{-print-file-name=libgcc.a}. This is useful when you use @option{-nostdlib} or @option{-nodefaultlibs} but you do want to link with @file{libgcc.a}. You can do -@example +@smallexample gcc -nostdlib @var{files}@dots{} `gcc -print-libgcc-file-name` -@end example +@end smallexample @item -print-search-dirs @opindex print-search-dirs Print the name of the configured installation directory and a list of -program and library directories gcc will search---and don't do anything else. +program and library directories @command{gcc} will search---and don't do anything else. -This is useful when gcc prints the error message +This is useful when @command{gcc} prints the error message @samp{installation problem, cannot exec cpp0: No such file or directory}. To resolve this you either need to put @file{cpp0} and the other compiler -components where gcc expects to find them, or you can set the environment +components where @command{gcc} expects to find them, or you can set the environment variable @env{GCC_EXEC_PREFIX} to the directory where you installed them. Don't forget the trailing '/'. @xref{Environment Variables}. @@ -3347,6 +3548,18 @@ anything else. @opindex dumpspecs Print the compiler's built-in specs---and don't do anything else. (This is used when GCC itself is being built.) @xref{Spec Files}. + +@item -feliminate-unused-debug-types +@opindex feliminate-unused-debug-types +Normally, when producing DWARF2 output, GCC will emit debugging +information for all types declared in a compilation +unit, regardless of whether or not they are actually used +in that compilation unit. Sometimes this is useful, such as +if, in the debugger, you want to cast a value to a type that is +not actually used in your program (but is declared). More often, +however, this results in a significant amount of wasted space. +With this option, GCC will avoid producing debug symbol output +for types that are nowhere used in the source file being compiled. @end table @node Optimize Options @@ -3368,6 +3581,14 @@ Turning on optimization flags makes the compiler attempt to improve the performance and/or code size at the expense of compilation time and possibly the ability to debug the program. +The compiler performs optimization based on the knowledge it has of +the program. Using the @option{-funit-at-a-time} flag will allow the +compiler to consider information gained from later functions in the +file when compiling a function. Compiling multiple files at once to a +single output file (and using @option{-funit-at-a-time}) will allow +the compiler to use information gained from all of the files when +compiling each of them. + Not all optimizations are controlled directly by a flag. Only optimizations that have a flag are listed. @@ -3383,12 +3604,11 @@ With @option{-O}, the compiler tries to reduce code size and execution time, without performing any optimizations that take a great deal of compilation time. -@option{-O} turns on the following optimization flags: +@option{-O} turns on the following optimization flags: @gccoptlist{-fdefer-pop @gol -fmerge-constants @gol -fthread-jumps @gol -floop-optimize @gol --fcrossjumping @gol -fif-conversion @gol -fif-conversion2 @gol -fdelayed-branch @gol @@ -3413,18 +3633,20 @@ also turns on the following optimization flags: -fstrength-reduce @gol -fcse-follow-jumps -fcse-skip-blocks @gol -frerun-cse-after-loop -frerun-loop-opt @gol --fgcse -fgcse-lm -fgcse-sm @gol +-fgcse -fgcse-lm -fgcse-sm -fgcse-las @gol -fdelete-null-pointer-checks @gol -fexpensive-optimizations @gol -fregmove @gol -fschedule-insns -fschedule-insns2 @gol --fsched-interblock -fsched-spec @gol +-fsched-interblock -fsched-spec @gol -fcaller-saves @gol -fpeephole2 @gol -freorder-blocks -freorder-functions @gol -fstrict-aliasing @gol +-funit-at-a-time @gol -falign-functions -falign-jumps @gol --falign-loops -falign-labels} +-falign-loops -falign-labels @gol +-fcrossjumping} Please note the warning under @option{-fgcse} about invoking @option{-O2} on programs that use computed gotos. @@ -3432,8 +3654,8 @@ invoking @option{-O2} on programs that use computed gotos. @item -O3 @opindex O3 Optimize yet more. @option{-O3} turns on all optimizations specified by -@option{-O2} and also turns on the @option{-finline-functions} and -@option{-frename-registers} options. +@option{-O2} and also turns on the @option{-finline-functions}, +@option{-fweb} and @option{-frename-registers} options. @item -O0 @opindex O0 @@ -3542,7 +3764,7 @@ Enabled at level @option{-O3}. @item -finline-limit=@var{n} @opindex finline-limit -By default, gcc limits the size of functions that can be inlined. This flag +By default, GCC limits the size of functions that can be inlined. This flag allows the control of this limit for functions that are explicitly marked as inline (i.e., marked with the inline keyword or defined within the class definition in c++). @var{n} is the size of functions that can be inlined in @@ -3556,12 +3778,10 @@ use inlining heavily such as those based on recursive templates with C++. Inlining is actually controlled by a number of parameters, which may be specified individually by using @option{--param @var{name}=@var{value}}. -The @option{-finline-limit=@var{n}} option sets some of these parameters +The @option{-finline-limit=@var{n}} option sets some of these parameters as follows: @table @gcctabopt - @item max-inline-insns - is set to @var{n}. @item max-inline-insns-single is set to @var{n}/2. @item max-inline-insns-auto @@ -3572,8 +3792,7 @@ as follows: is set to @var{n}. @end table -Using @option{-finline-limit=600} thus results in the default settings -for these parameters. See below for a documentation of the individual +See below for a documentation of the individual parameters controlling inlining. @emph{Note:} pseudo instruction represents, in this particular context, an @@ -3617,6 +3836,12 @@ types. Languages like C or C++ require each non-automatic variable to have distinct location, so using this option will result in non-conforming behavior. +@item -fnew-ra +@opindex fnew-ra +Use a graph coloring register allocator. Currently this option is meant +only for testing. Users should not specify this option, since it is not +yet ready for production use. + @item -fno-branch-count-reg @opindex fno-branch-count-reg Do not use ``decrement and branch'' instructions on a count register, @@ -3725,10 +3950,19 @@ Enabled by default when gcse is enabled. @item -fgcse-sm @opindex fgcse-sm -When @option{-fgcse-sm} is enabled, A store motion pass is run after global common -subexpression elimination. This pass will attempt to move stores out of loops. -When used in conjunction with @option{-fgcse-lm}, loops containing a load/store sequence -can be changed to a load before the loop and a store after the loop. +When @option{-fgcse-sm} is enabled, a store motion pass is run after +global common subexpression elimination. This pass will attempt to move +stores out of loops. When used in conjunction with @option{-fgcse-lm}, +loops containing a load/store sequence can be changed to a load before +the loop and a store after the loop. + +Enabled by default when gcse is enabled. + +@item -fgcse-las +@opindex fgcse-las +When @option{-fgcse-las} is enabled, the global common subexpression +elimination pass eliminates redundant loads that come after stores to the +same memory location (both partial and full redundancies). Enabled by default when gcse is enabled. @@ -3848,6 +4082,42 @@ Allow speculative motion of more load instructions. This only makes sense when scheduling before register allocation, i.e.@: with @option{-fschedule-insns} or at @option{-O2} or higher. +@item -fsched-stalled-insns=@var{n} +@opindex fsched-stalled-insns +Define how many insns (if any) can be moved prematurely from the queue +of stalled insns into the ready list, during the second scheduling pass. + +@item -fsched-stalled-insns-dep=@var{n} +@opindex fsched-stalled-insns-dep +Define how many insn groups (cycles) will be examined for a dependency +on a stalled insn that is candidate for premature removal from the queue +of stalled insns. Has an effect only during the second scheduling pass, +and only if @option{-fsched-stalled-insns} is used and its value is not zero. + +@item -fsched2-use-superblocks +@opindex fsched2-use-superblocks +When scheduling after register allocation, do use superblock scheduling +algorithm. Superblock scheduling allows motion across basic block boundaries +resulting on faster schedules. This option is experimental, as not all machine +descriptions used by GCC model the CPU closely enough to avoid unreliable +results from the algorithm. + +This only makes sense when scheduling after register allocation, i.e.@: with +@option{-fschedule-insns2} or at @option{-O2} or higher. + +@item -fsched2-use-traces +@opindex fsched2-use-traces +Use @option{-fsched2-use-superblocks} algorithm when scheduling after register +allocation and additionally perform code duplication in order to increase the +size of superblocks using tracer pass. See @option{-ftracer} for details on +trace formation. + +This mode should produce faster but significantly longer programs. Also +without @code{-fbranch-probabilities} the traces constructed may not match the +reality and hurt the performance. This only makes +sense when scheduling after register allocation, i.e.@: with +@option{-fschedule-insns2} or at @option{-O2} or higher. + @item -fcaller-saves @opindex fcaller-saves Enable values to be allocated in registers that will be clobbered by @@ -3881,11 +4151,10 @@ These two options are intended to be removed someday, once they have helped determine the efficacy of various approaches to improving loop optimizations. -Please let us (@w{@email{gcc@@gcc.gnu.org}} and @w{@email{fortran@@gnu.org}}) -know how use of these options affects -the performance of your production code. -We're very interested in code that runs @emph{slower} -when these options are @emph{enabled}. +Please contact @w{@email{gcc@@gcc.gnu.org}}, and describe how use of +these options affects the performance of your production code. +Examples of code that runs @emph{slower} when these options are +@emph{enabled} are very valuable. @item -fno-peephole @itemx -fno-peephole2 @@ -3899,12 +4168,11 @@ other, a few use both. @option{-fpeephole} is enabled by default. @option{-fpeephole2} enabled at levels @option{-O2}, @option{-O3}, @option{-Os}. -@item -fbranch-probabilities @item -fno-guess-branch-probability @opindex fno-guess-branch-probability Do not guess branch probabilities using a randomized model. -Sometimes gcc will opt to use a randomized model to guess branch +Sometimes GCC will opt to use a randomized model to guess branch probabilities, when none are available from either profiling feedback (@option{-fprofile-arcs}) or @samp{__builtin_expect}. This means that different runs of the compiler on the same program may produce different @@ -3952,7 +4220,7 @@ example, an @code{unsigned int} can alias an @code{int}, but not a type. Pay special attention to code like this: -@example +@smallexample union a_union @{ int i; double d; @@ -3963,13 +4231,13 @@ int f() @{ t.d = 3.0; return t.i; @} -@end example +@end smallexample The practice of reading from a different union member than the one most recently written to (called ``type-punning'') is common. Even with @option{-fstrict-aliasing}, type-punning is allowed, provided the memory is accessed through the union type. So, the code above will work as expected. However, this code might not: -@example +@smallexample int f() @{ a_union t; int* ip; @@ -3977,7 +4245,7 @@ int f() @{ ip = &t.i; return *ip; @} -@end example +@end smallexample Every language that wishes to perform language-specific alias analysis should define a function that computes, given an @code{tree} @@ -4063,6 +4331,15 @@ will most benefit processors with lots of registers. It can, however, make debugging impossible, since variables will no longer stay in a ``home register''. +@item -fweb +@opindex fweb +Constructs webs as commonly used for register allocation purposes and assign +each web individual pseudo register. This allows the register allocation pass +to operate on pseudos directly, but also strengthens several other optimization +passes, such as CSE, loop optimizer and trivial dead code remover. It can, +however, make debugging impossible, since variables will no longer stay in a +``home register''. + Enabled at levels @option{-O3}. @item -fno-cprop-registers @@ -4073,6 +4350,24 @@ and occasionally eliminate the copy. Disabled at levels @option{-O}, @option{-O2}, @option{-O3}, @option{-Os}. +@item -fprofile-generate +@opindex fprofile-generate + +Enable options usually used for instrumenting application to produce +profile useful for later recompilation with profile feedback based +optimization. You must use @code{-fprofile-generate} both when +compiling and when linking your program. + +The following options are enabled: @code{-fprofile-arcs}, @code{-fprofile-values}, @code{-fvpt}. + +@item -fprofile-use +@opindex fprofile-use +Enable profile feedback directed optimizations, and optimizations +generally profitable only with profile feedback available. + +The following options are enabled: @code{-fbranch-probabilities}, +@code{-fvpt}, @code{-funroll-loops}, @code{-fpeel-loops}, @code{-ftracer}. + @end table The following options control compiler behavior regarding floating @@ -4098,8 +4393,8 @@ them to store all pertinent intermediate computations into variables. @item -ffast-math @opindex ffast-math Sets @option{-fno-math-errno}, @option{-funsafe-math-optimizations}, @* -@option{-fno-trapping-math}, @option{-ffinite-math-only} and @* -@option{-fno-signaling-nans}. +@option{-fno-trapping-math}, @option{-ffinite-math-only}, +@option{-fno-rounding-math} and @option{-fno-signaling-nans}. This option causes the preprocessor macro @code{__FAST_MATH__} to be defined. @@ -4163,6 +4458,26 @@ math functions. The default is @option{-ftrapping-math}. +@item -frounding-math +@opindex frounding-math +Disable transformations and optimizations that assume default floating +point rounding behavior. This is round-to-zero for all floating point +to integer conversions, and round-to-nearest for all other arithmetic +truncations. This option should be specified for programs that change +the FP rounding mode dynamically, or that may be executed with a +non-default rounding mode. This option disables constant folding of +floating point expressions at compile-time (which may be affected by +rounding mode) and arithmetic transformations that are unsafe in the +presence of sign-dependent rounding modes. + +The default is @option{-fno-rounding-math}. + +This option is experimental and does not currently guarantee to +disable all GCC optimizations that are affected by rounding mode. +Future versions of GCC may provide finer control of this setting +using C99's @code{FENV_ACCESS} pragma. This command line option +will be used to specify the default state for @code{FENV_ACCESS}. + @item -fsignaling-nans @opindex fsignaling-nans Compile code assuming that IEEE signaling NaNs may generate user-visible @@ -4199,18 +4514,37 @@ After running a program compiled with @option{-fprofile-arcs} @option{-fbranch-probabilities}, to improve optimizations based on the number of times each branch was taken. When the program compiled with @option{-fprofile-arcs} exits it saves arc execution -counts to a file called @file{@var{sourcename}.da} for each source +counts to a file called @file{@var{sourcename}.gcda} for each source file The information in this data file is very dependent on the structure of the generated code, so you must use the same source code and the same optimization options for both compilations. -With @option{-fbranch-probabilities}, GCC puts a +With @option{-fbranch-probabilities}, GCC puts a @samp{REG_BR_PROB} note on each @samp{JUMP_INSN} and @samp{CALL_INSN}. These can be used to improve optimization. Currently, they are only used in one place: in @file{reorg.c}, instead of guessing which path a branch is mostly to take, the @samp{REG_BR_PROB} values are used to exactly determine which path is taken more often. +@item -fprofile-values +@opindex fprofile-values +If combined with @option{-fprofile-arcs}, it adds code so that some +data about values of expressions in the program is gathered. + +With @option{-fbranch-probabilities}, it reads back the data gathered +from profiling values of expressions and adds @samp{REG_VALUE_PROFILE} +notes to instructions for their later usage in optimizations. + +@item -fvpt +@opindex fvpt +If combined with @option{-fprofile-arcs}, it instructs the compiler to add +a code to gather information about values of expressions. + +With @option{-fbranch-probabilities}, it reads back the data gathered +and actually performs the optimizations based on them. +Currently the optimizations include specialization of division operation +using the knowledge about the value of the denominator. + @item -fnew-ra @opindex fnew-ra Use a graph coloring register allocator. Currently this option is meant @@ -4223,19 +4557,63 @@ Perform tail duplication to enlarge superblock size. This transformation simplifies the control flow of the function allowing other optimizations to do better job. +@item -funit-at-a-time +@opindex funit-at-a-time +Parse the whole compilation unit before starting to produce code. +This allows some extra optimizations to take place but consumes more +memory. + @item -funroll-loops @opindex funroll-loops -Unroll loops whose number of iterations can be determined at compile -time or upon entry to the loop. @option{-funroll-loops} implies both -@option{-fstrength-reduce} and @option{-frerun-cse-after-loop}. This -option makes code larger, and may or may not make it run faster. +Unroll loops whose number of iterations can be determined at compile time or +upon entry to the loop. @option{-funroll-loops} implies +@option{-frerun-cse-after-loop}. It also turns on complete loop peeling +(i.e. complete removal of loops with small constant number of iterations). +This option makes code larger, and may or may not make it run faster. @item -funroll-all-loops @opindex funroll-all-loops Unroll all loops, even if their number of iterations is uncertain when the loop is entered. This usually makes programs run more slowly. @option{-funroll-all-loops} implies the same options as -@option{-funroll-loops}, +@option{-funroll-loops}. + +@item -fpeel-loops +@opindex fpeel-loops +Peels the loops for that there is enough information that they do not +roll much (from profile feedback). It also turns on complete loop peeling +(i.e. complete removal of loops with small constant number of iterations). + +@item -funswitch-loops +@opindex funswitch-loops +Move branches with loop invariant conditions out of the loop, with duplicates +of the loop on both branches (modified according to result of the condition). + +@item -fold-unroll-loops +@opindex fold-unroll-loops +Unroll loops whose number of iterations can be determined at compile +time or upon entry to the loop, using the old loop unroller whose loop +recognition is based on notes from frontend. @option{-fold-unroll-loops} implies +both @option{-fstrength-reduce} and @option{-frerun-cse-after-loop}. This +option makes code larger, and may or may not make it run faster. + +@item -fold-unroll-all-loops +@opindex fold-unroll-all-loops +Unroll all loops, even if their number of iterations is uncertain when +the loop is entered. This is done using the old loop unroller whose loop +recognition is based on notes from frontend. This usually makes programs run more slowly. +@option{-fold-unroll-all-loops} implies the same options as +@option{-fold-unroll-loops}. + +@item -funswitch-loops +@opindex funswitch-loops +Move branches with loop invariant conditions out of the loop, with duplicates +of the loop on both branches (modified according to result of the condition). + +@item -funswitch-loops +@opindex funswitch-loops +Move branches with loop invariant conditions out of the loop, with duplicates +of the loop on both branches (modified according to result of the condition). @item -fprefetch-loop-arrays @opindex fprefetch-loop-arrays @@ -4266,23 +4644,18 @@ You will not be able to use @code{gprof} on all systems if you specify this option and you may have problems with debugging if you specify both this option and @option{-g}. -@item -fssa -@opindex fssa -Perform optimizations in static single assignment form. Each function's -flow graph is translated into SSA form, optimizations are performed, and -the flow graph is translated back from SSA form. Users should not -specify this option, since it is not yet ready for production use. - -@item -fssa-ccp -@opindex fssa-ccp -Perform Sparse Conditional Constant Propagation in SSA form. Requires -@option{-fssa}. Like @option{-fssa}, this is an experimental feature. - -@item -fssa-dce -@opindex fssa-dce -Perform aggressive dead-code elimination in SSA form. Requires @option{-fssa}. -Like @option{-fssa}, this is an experimental feature. +@item -fbranch-target-load-optimize +@opindex fbranch-target-load-optimize +Perform branch target register load optimization before prologue / epilogue +threading. +The use of target registers can typically be exposed only during reload, +thus hoisting loads out of loops and doing inter-block scheduling needs +a separate optimization pass. +@item -fbranch-target-load-optimize2 +@opindex fbranch-target-load-optimize2 +Perform branch target register load optimization after prologue / epilogue +threading. @item --param @var{name}=@var{value} @opindex param @@ -4292,6 +4665,10 @@ that contain more that a certain number of instructions. You can control some of these constants on the command-line using the @option{--param} option. +The names of specific parameters, and the meaning of the values, are +tied to the internals of the compiler, and are subject to change +without notice in future releases. + In each case, the @var{value} is an integer. The allowable choices for @var{name} are given in the following table: @@ -4336,11 +4713,11 @@ needlessly consume memory and resources. @item max-inline-insns-single Several parameters control the tree inliner used in gcc. -This number sets the maximum number of instructions (counted in gcc's -internal representation) in a single function that the tree inliner +This number sets the maximum number of instructions (counted in GCC's +internal representation) in a single function that the tree inliner will consider for inlining. This only affects functions declared inline and methods implemented in a class declaration (C++). -The default value is 300. +The default value is 500. @item max-inline-insns-auto When you use @option{-finline-functions} (included in @option{-O3}), @@ -4348,45 +4725,65 @@ a lot of functions that would otherwise not be considered for inlining by the compiler will be investigated. To those functions, a different (more restrictive) limit compared to functions declared inline can be applied. -The default value is 300. - -@item max-inline-insns -The tree inliner does decrease the allowable size for single functions -to be inlined after we already inlined the number of instructions -given here by repeated inlining. This number should be a factor of -two or more larger than the single function limit. -Higher numbers result in better runtime performance, but incur higher -compile-time resource (CPU time, memory) requirements and result in -larger binaries. Very high values are not advisable, as too large -binaries may adversely affect runtime performance. -The default value is 600. - -@item max-inline-slope -After exceeding the maximum number of inlined instructions by repeated -inlining, a linear function is used to decrease the allowable size -for single functions. The slope of that function is the negative -reciprocal of the number specified here. -The default value is 32. - -@item min-inline-insns -The repeated inlining is throttled more and more by the linear function -after exceeding the limit. To avoid too much throttling, a minimum for -this function is specified here to allow repeated inlining for very small -functions even when a lot of repeated inlining already has been done. -The default value is 130. +The default value is 100. + +@item large-function-insns +The limit specifying really large functions. For functions greater than this +limit inlining is constrained by @option{--param large-function-growth}. +This parameter is useful primarily to avoid extreme compilation time caused by non-linear +algorithms used by the backend. +This parameter is ignored when @option{-funit-at-a-time} is not used. +The default value is 3000. + +@item large-function-growth +Specifies maximal growth of large function caused by inlining in percents. +This parameter is ignored when @option{-funit-at-a-time} is not used. +The default value is 200. + +@item inline-unit-growth +Specifies maximal overall growth of the compilation unit caused by inlining. +This parameter is ignored when @option{-funit-at-a-time} is not used. +The default value is 150. @item max-inline-insns-rtl For languages that use the RTL inliner (this happens at a later stage -than tree inlining), you can set the maximum allowable size (counted +than tree inlining), you can set the maximum allowable size (counted in RTL instructions) for the RTL inliner with this parameter. The default value is 600. - @item max-unrolled-insns The maximum number of instructions that a loop should have if that loop is unrolled, and if the loop is unrolled, it determines how many times the loop code is unrolled. +@item max-average-unrolled-insns +The maximum number of instructions biased by probabilities of their execution +that a loop should have if that loop is unrolled, and if the loop is unrolled, +it determines how many times the loop code is unrolled. + +@item max-unroll-times +The maximum number of unrollings of a single loop. + +@item max-peeled-insns +The maximum number of instructions that a loop should have if that loop +is peeled, and if the loop is peeled, it determines how many times +the loop code is peeled. + +@item max-peel-times +The maximum number of peelings of a single loop. + +@item max-completely-peeled-insns +The maximum number of insns of a completely peeled loop. + +@item max-completely-peel-times +The maximum number of iterations of a loop to be suitable for complete peeling. + +@item max-unswitch-insns +The maximum number of insns of an unswitched loop. + +@item max-unswitch-level +The maximum number of branches unswitched in a single loop. + @item hot-bb-count-fraction Select fraction of the maximal count of repetitions of basic block in program given basic block needs to have to be considered hot. @@ -4428,6 +4825,10 @@ compilation for profile feedback and one for compilation without. The value for compilation with profile feedback needs to be more conservative (higher) in order to make tracer effective. +@item max-cse-path-length + +Maximum number of basic blocks on path that cse considers. + @item ggc-min-expand GCC uses a garbage collector to manage its own memory allocation. This @@ -4462,6 +4863,29 @@ parameter very large effectively disables garbage collection. Setting this parameter and @option{ggc-min-expand} to zero causes a full collection to occur at every opportunity. +@item max-reload-search-insns +The maximum number of instruction reload should look backward for equivalent +register. Increasing values mean more aggressive optimization, making the +compile time increase with probably slightly better performance. The default +value is 100. + +@item max-cselib-memory-location +The maximum number of memory locations cselib should take into acount. +Increasing values mean more aggressive optimization, making the compile time +increase with probably slightly better performance. The default value is 500. + +@item reorder-blocks-duplicate +@itemx reorder-blocks-duplicate-feedback + +Used by basic block reordering pass to decide whether to use unconditional +branch or duplicate the code on its destination. Code is duplicated when its +estimated size is smaller than this value multiplied by the estimated size of +unconditional jump in the hot spots of the program. + +The @option{reorder-block-duplicate-feedback} is used only when profile +feedback is available and may be set to higher values than +@option{reorder-block-duplicate} since information about the hot spots is more +accurate. @end table @end table @@ -4478,6 +4902,7 @@ Some of these options make sense only together with @option{-E} because they cause the preprocessor output to be unsuitable for actual compilation. +@table @gcctabopt @opindex Wp You can use @option{-Wp,@var{option}} to bypass the compiler driver and pass @var{option} directly through to the preprocessor. If @@ -4489,6 +4914,16 @@ interface is undocumented and subject to change, so whenever possible you should avoid using @option{-Wp} and let the driver handle the options instead. +@item -Xpreprocessor @var{option} +@opindex preprocessor +Pass @var{option} as an option to the preprocessor. You can use this to +supply system-specific preprocessor options which GCC does not know how to +recognize. + +If you want to pass an option that takes an argument, you must use +@option{-Xpreprocessor} twice, once for the option and once for the argument. +@end table + @include cppopts.texi @node Assembler Options @@ -4502,6 +4937,16 @@ You can pass options to the assembler. @opindex Wa Pass @var{option} as an option to the assembler. If @var{option} contains commas, it is split into multiple options at the commas. + +@item -Xassembler @var{option} +@opindex Xassembler +Pass @var{option} as an option to the assembler. You can use this to +supply system-specific assembler options which GCC does not know how to +recognize. + +If you want to pass an option that takes an argument, you must use +@option{-Xassembler} twice, once for the option and once for the argument. + @end table @node Link Options @@ -4615,6 +5060,13 @@ library subroutines. (For example, @samp{__main}, used to ensure C++ constructors will be called; @pxref{Collect2,,@code{collect2}, gccint, GNU Compiler Collection (GCC) Internals}.) +@item -pie +@opindex pie +Produce a position independent executable on targets which support it. +For predictable results, you must also specify the same set of options +that were used to generate code (@option{-fpie}, @option{-fPIE}, +or model suboptions) when you specify this option. + @item -s @opindex s Remove all symbol table and relocation information from the executable. @@ -4659,14 +5111,14 @@ this is the right thing to do. If, instead, you use the GCC driver to create shared libraries, you may find that they will not always be linked with the shared @file{libgcc}. -If GCC finds, at its configuration time, that you have a GNU linker that -does not support option @option{--eh-frame-hdr}, it will link the shared -version of @file{libgcc} into shared libraries by default. Otherwise, -it will take advantage of the linker and optimize away the linking with -the shared version of @file{libgcc}, linking with the static version of -libgcc by default. This allows exceptions to propagate through such -shared libraries, without incurring relocation costs at library load -time. +If GCC finds, at its configuration time, that you have a non-GNU linker +or a GNU linker that does not support option @option{--eh-frame-hdr}, +it will link the shared version of @file{libgcc} into shared libraries +by default. Otherwise, it will take advantage of the linker and optimize +away the linking with the shared version of @file{libgcc}, linking with +the static version of libgcc by default. This allows exceptions to +propagate through such shared libraries, without incurring relocation +costs at library load time. However, if a library or main executable is supposed to throw or catch exceptions, you must link it using the G++ or GCJ driver, as appropriate @@ -4777,7 +5229,7 @@ without @samp{@var{machine}/@var{version}/} (@pxref{Target Options}). For each subprogram to be run, the compiler driver first tries the @option{-B} prefix, if any. If that name is not found, or if @option{-B} was not specified, the driver tries two standard prefixes, which are -@file{/usr/lib/gcc/} and @file{/usr/local/lib/gcc-lib/}. If neither of +@file{/usr/lib/gcc/} and @file{/usr/local/lib/gcc/}. If neither of those results in a file name that is found, the unmodified program name is searched for using the directories specified in your @env{PATH} environment variable. @@ -5022,6 +5474,15 @@ of a temporary file, just like @samp{%u}. This temporary file is not meant for communication between processes, but rather as a junk disposal mechanism. +@item %|@var{suffix} +@itemx %m@var{suffix} +Like @samp{%g}, except if @option{-pipe} is in effect. In that case +@samp{%|} substitutes a single dash and @samp{%m} substitutes nothing at +all. These are the two most common ways to instruct a program that it +should read from standard input or write to standard output. If you +need something more elaborate you can use an @samp{%@{pipe:@code{X}@}} +construct: see for example @file{f/lang-specs.h}. + @item %.@var{SUFFIX} Substitutes @var{.SUFFIX} for the suffixes of a matched switch's args when it is subsequently output with @samp{%*}. @var{SUFFIX} is @@ -5061,7 +5522,10 @@ predefined macro, except for macros that start with @samp{__} or with C@. @item %I -Substitute a @option{-iprefix} option made from @env{GCC_EXEC_PREFIX}. +Substitute any of @option{-iprefix} (made from @env{GCC_EXEC_PREFIX}), +@option{-isysroot} (made from @env{TARGET_SYSTEM_ROOT}), and +@option{-isystem} (made from @env{COMPILER_PATH} and @option{-B} options) +as necessary. @item %s Current argument is the name of a library or startup file of some sort. @@ -5072,9 +5536,6 @@ the full name found. Print @var{str} as an error message. @var{str} is terminated by a newline. Use this when inconsistent options are detected. -@item %| -Output @samp{-} if the input for the current command is coming from a pipe. - @item %(@var{name}) Substitute the contents of spec string @var{name} at this point. @@ -5094,18 +5555,6 @@ Output the accumulated assembler options specified by @option{-Wa}. @item %Z Output the accumulated preprocessor options specified by @option{-Wp}. -@item %v1 -Substitute the major version number of GCC@. -(For version 2.9.5, this is 2.) - -@item %v2 -Substitute the minor version number of GCC@. -(For version 2.9.5, this is 9.) - -@item %v3 -Substitute the patch level number of GCC@. -(For version 2.9.5, this is 5.) - @item %a Process the @code{asm} spec. This is used to compute the switches to be passed to the assembler. @@ -5171,6 +5620,12 @@ Substitute the variable part of a matched option. See below. Note that each comma in the substituted string is replaced by a single space. +@item %<@code{S} +Remove all occurrences of @code{-S} from the command line. Note---this +command is position dependent. @samp{%} commands in the spec string +before this one will see @code{-S}, @samp{%} commands in the spec string +after this one will not. + @item %:@var{function}(@var{args}) Call the named function @var{function}, passing it @var{args}. @var{args} is first processed as a nested spec string, then split @@ -5199,12 +5654,12 @@ returns the pathname. If it does not exist, it returns the second argument. This way, @code{if-exists-else} can be used to select one file or another, based on the existence of the first. Here is a small example of its usage: -@smallexample +@smallexample *startfile: crt0%O%s %:if-exists(crti%O%s) \ %:if-exists-else(crtbeginT%O%s crtbegin%O%s) @end smallexample -@end table +@end table @item %@{@code{S}@} Substitutes the @code{-S} switch, if that switch was given to GCC@. @@ -5226,51 +5681,40 @@ GCC considers @option{-o foo} as being one switch whose names starts with @samp{o}. %@{o*@} would substitute this text, including the space. Thus two arguments would be generated. -@item %@{^@code{S}*@} -Like %@{@code{S}*@}, but don't put a blank between a switch and its -argument. Thus %@{^o*@} would only generate one argument, not two. - @item %@{@code{S}*&@code{T}*@} Like %@{@code{S}*@}, but preserve order of @code{S} and @code{T} options (the order of @code{S} and @code{T} in the spec is not significant). There can be any number of ampersand-separated variables; for each the wild card is optional. Useful for CPP as @samp{%@{D*&U*&A*@}}. -@item %@{<@code{S}@} -Remove all occurrences of @code{-S} from the command line. Note---this -command is position dependent. @samp{%} commands in the spec string -before this option will see @code{-S}, @samp{%} commands in the spec -string after this option will not. - -@item %@{@code{S}*:@code{X}@} -Substitutes @code{X} if one or more switches whose names start with -@code{-S} are specified to GCC@. Note that the tail part of the -@code{-S} option (i.e.@: the part matched by the @samp{*}) will be substituted -for each occurrence of @samp{%*} within @code{X}. - @item %@{@code{S}:@code{X}@} -Substitutes @code{X}, but only if the @samp{-S} switch was given to GCC@. +Substitutes @code{X}, if the @samp{-S} switch was given to GCC@. @item %@{!@code{S}:@code{X}@} -Substitutes @code{X}, but only if the @samp{-S} switch was @emph{not} given to GCC@. - -@item %@{|@code{S}:@code{X}@} -Like %@{@code{S}:@code{X}@}, but if no @code{S} switch, substitute @samp{-}. +Substitutes @code{X}, if the @samp{-S} switch was @emph{not} given to GCC@. -@item %@{|!@code{S}:@code{X}@} -Like %@{!@code{S}:@code{X}@}, but if there is an @code{S} switch, substitute @samp{-}. +@item %@{@code{S}*:@code{X}@} +Substitutes @code{X} if one or more switches whose names start with +@code{-S} are specified to GCC@. Normally @code{X} is substituted only +once, no matter how many such switches appeared. However, if @code{%*} +appears somewhere in @code{X}, then @code{X} will be substituted once +for each matching switch, with the @code{%*} replaced by the part of +that switch that matched the @code{*}. @item %@{.@code{S}:@code{X}@} -Substitutes @code{X}, but only if processing a file with suffix @code{S}. +Substitutes @code{X}, if processing a file with suffix @code{S}. @item %@{!.@code{S}:@code{X}@} -Substitutes @code{X}, but only if @emph{not} processing a file with suffix @code{S}. +Substitutes @code{X}, if @emph{not} processing a file with suffix @code{S}. @item %@{@code{S}|@code{P}:@code{X}@} -Substitutes @code{X} if either @code{-S} or @code{-P} was given to GCC@. This may be -combined with @samp{!} and @samp{.} sequences as well, although they -have a stronger binding than the @samp{|}. For example a spec string -like this: +Substitutes @code{X} if either @code{-S} or @code{-P} was given to GCC@. +This may be combined with @samp{!}, @samp{.}, and @code{*} sequences as well, +although they have a stronger binding than the @samp{|}. If @code{%*} +appears in @code{X}, all of the alternatives must be starred, and only +the first matching alternative is substituted. + +For example, a spec string like this: @smallexample %@{.c:-foo@} %@{!.c:-bar@} %@{.c|d:-baz@} %@{!.c|d:-boggle@} @@ -5286,23 +5730,33 @@ jim.d -bar -boggle -d jim.d -bar -baz -boggle @end smallexample +@item %@{S:X; T:Y; :D@} + +If @code{S} was given to GCC, substitutes @code{X}; else if @code{T} was +given to GCC, substitutes @code{Y}; else substitutes @code{D}. There can +be as many clauses as you need. This may be combined with @code{.}, +@code{!}, @code{|}, and @code{*} as needed. + + @end table -The conditional text @code{X} in a %@{@code{S}:@code{X}@} or -%@{!@code{S}:@code{X}@} construct may contain other nested @samp{%} constructs -or spaces, or even newlines. They are processed as usual, as described -above. +The conditional text @code{X} in a %@{@code{S}:@code{X}@} or similar +construct may contain other nested @samp{%} constructs or spaces, or +even newlines. They are processed as usual, as described above. +Trailing white space in @code{X} is ignored. White space may also +appear anywhere on the left side of the colon in these constructs, +except between @code{.} or @code{*} and the corresponding word. -The @option{-O}, @option{-f}, @option{-m}, and @option{-W} -switches are handled specifically in these -constructs. If another value of @option{-O} or the negated form of a @option{-f}, @option{-m}, or -@option{-W} switch is found later in the command line, the earlier switch -value is ignored, except with @{@code{S}*@} where @code{S} is just one -letter, which passes all matching options. +The @option{-O}, @option{-f}, @option{-m}, and @option{-W} switches are +handled specifically in these constructs. If another value of +@option{-O} or the negated form of a @option{-f}, @option{-m}, or +@option{-W} switch is found later in the command line, the earlier +switch value is ignored, except with @{@code{S}*@} where @code{S} is +just one letter, which passes all matching options. -The character @samp{|} at the beginning of the predicate text is used to indicate -that a command should be piped to the following command, but only if @option{-pipe} -is specified. +The character @samp{|} at the beginning of the predicate text is used to +indicate that a command should be piped to the following command, but +only if @option{-pipe} is specified. It is built into GCC which switches take arguments and which do not. (You might think it would be useful to generalize this to allow each @@ -5387,13 +5841,10 @@ that macro, which enables you to change the defaults. * VAX Options:: * SPARC Options:: * ARM Options:: -* MN10200 Options:: * MN10300 Options:: * M32R/D Options:: -* M88K Options:: * RS/6000 and PowerPC Options:: * Darwin Options:: -* RT Options:: * MIPS Options:: * i386 and x86-64 Options:: * HPPA Options:: @@ -5508,10 +5959,6 @@ This results in code which can run relatively efficiently on either a 68020/68881 or a 68030 or a 68040. The generated code does use the 68881 instructions that are emulated on the 68060. -@item -mfpa -@opindex mfpa -Generate output containing Sun FPA instructions for floating point. - @item -msoft-float @opindex msoft-float Generate output containing library calls for floating point. @@ -5590,6 +6037,30 @@ not presently supported with @option{-mpcrel}, though this could be supported fo Do not (do) assume that unaligned memory references will be handled by the system. +@item -msep-data +Generate code that allows the data segment to be located in a different +area of memory from the text segment. This allows for execute in place in +an environment without virtual memory management. This option implies -fPIC. + +@item -mno-sep-data +Generate code that assumes that the data segment follows the text segment. +This is the default. + +@item -mid-shared-library +Generate code that supports shared libraries via the library ID method. +This allows for execute in place and shared libraries in an environment +without virtual memory management. This option implies -fPIC. + +@item -mno-id-shared-library +Generate code that doesn't assume ID based shared libraries are being used. +This is the default. + +@item -mshared-library-id=n +Specified the identification number of the ID based shared library being +compiled. Specifying a value of 0 will generate more compact code, specifying +other values will force the allocation of that number to the current +library but is no more space or time efficient than omitting this option. + @end table @node M68hc1x Options @@ -5620,7 +6091,7 @@ when the compiler is configured for 68HC12-based systems. @itemx -m68hcs12 @opindex m68S12 @opindex m68hcs12 -Generate output for a 68HCS12. +Generate output for a 68HCS12. @item -mauto-incdec @opindex mauto-incdec @@ -5681,7 +6152,7 @@ Output code for g-format floating point numbers instead of d-format. @subsection SPARC Options @cindex SPARC options -These @samp{-m} switches are supported on the SPARC: +These @samp{-m} options are supported on the SPARC: @table @gcctabopt @item -mno-app-regs @@ -5732,7 +6203,7 @@ Generate output containing library calls for quad-word (long double) floating point instructions. The functions called are those specified in the SPARC ABI@. This is the default. -As of this writing, there are no sparc implementations that have hardware +As of this writing, there are no SPARC implementations that have hardware support for the quad-word floating point instructions. They all invoke a trap handler for one of these instructions, and then the trap handler emulates the effect of the instruction. Because of the trap handler overhead, @@ -5753,6 +6224,8 @@ The local registers and the input registers (0--5) are still treated as With @option{-mno-flat} (the default), the compiler emits save/restore instructions (except for leaf functions) and is the normal mode of operation. +These options are deprecated and will be deleted in a future GCC release. + @item -mno-unaligned-doubles @itemx -munaligned-doubles @opindex mno-unaligned-doubles @@ -5784,7 +6257,7 @@ the rules of the ABI@. @option{-mimpure-text}, used in addition to @option{-shared}, tells the compiler to not pass @option{-z text} to the linker when linking a shared object. Using this option, you can link position-dependent -code into a shared object. +code into a shared object. @option{-mimpure-text} suppresses the ``relocations remain against allocatable but non-writable sections'' linker error message. @@ -5800,35 +6273,18 @@ This option is only available on SunOS and Solaris. @opindex mv8 @opindex msparclite These two options select variations on the SPARC architecture. - -By default (unless specifically configured for the Fujitsu SPARClite), -GCC generates code for the v7 variant of the SPARC architecture. - -@option{-mv8} will give you SPARC v8 code. The only difference from v7 -code is that the compiler emits the integer multiply and integer -divide instructions which exist in SPARC v8 but not in SPARC v7. - -@option{-msparclite} will give you SPARClite code. This adds the integer -multiply, integer divide step and scan (@code{ffs}) instructions which -exist in SPARClite but not in SPARC v7. - These options are deprecated and will be deleted in a future GCC release. They have been replaced with @option{-mcpu=xxx}. @item -mcypress @itemx -msupersparc +@itemx -mf930 +@itemx -mf934 @opindex mcypress @opindex msupersparc -These two options select the processor for which the code is optimized. - -With @option{-mcypress} (the default), the compiler optimizes code for the -Cypress CY7C602 chip, as used in the SPARCStation/SPARCServer 3xx series. -This is also appropriate for the older SPARCStation 1, 2, IPX etc. - -With @option{-msupersparc} the compiler optimizes code for the SuperSPARC cpu, as -used in the SPARCStation 10, 1000 and 2000 series. This flag also enables use -of the full SPARC v8 instruction set. - +@opindex -mf930 +@opindex -mf934 +These four options select the processor for which the code is optimized. These options are deprecated and will be deleted in a future GCC release. They have been replaced with @option{-mcpu=xxx}. @@ -5837,7 +6293,7 @@ They have been replaced with @option{-mcpu=xxx}. Set the instruction set, register set, and instruction scheduling parameters for machine type @var{cpu_type}. Supported values for @var{cpu_type} are @samp{v7}, @samp{cypress}, @samp{v8}, @samp{supersparc}, @samp{sparclite}, -@samp{hypersparc}, @samp{sparclite86x}, @samp{f930}, @samp{f934}, +@samp{f930}, @samp{f934}, @samp{hypersparc}, @samp{sparclite86x}, @samp{sparclet}, @samp{tsc701}, @samp{v9}, @samp{ultrasparc}, and @samp{ultrasparc3}. @@ -5856,6 +6312,41 @@ implementations. v9: ultrasparc, ultrasparc3 @end smallexample +By default (unless configured otherwise), GCC generates code for the V7 +variant of the SPARC architecture. With @option{-mcpu=cypress}, the compiler +additionally optimizes it for the Cypress CY7C602 chip, as used in the +SPARCStation/SPARCServer 3xx series. This is also appropriate for the older +SPARCStation 1, 2, IPX etc. + +With @option{-mcpu=v8}, GCC generates code for the V8 variant of the SPARC +architecture. The only difference from V7 code is that the compiler emits +the integer multiply and integer divide instructions which exist in SPARC-V8 +but not in SPARC-V7. With @option{-mcpu=supersparc}, the compiler additionally +optimizes it for the SuperSPARC chip, as used in the SPARCStation 10, 1000 and +2000 series. + +With @option{-mcpu=sparclite}, GCC generates code for the SPARClite variant of +the SPARC architecture. This adds the integer multiply, integer divide step +and scan (@code{ffs}) instructions which exist in SPARClite but not in SPARC-V7. +With @option{-mcpu=f930}, the compiler additionally optimizes it for the +Fujitsu MB86930 chip, which is the original SPARClite, with no FPU. With +@option{-mcpu=f934}, the compiler additionally optimizes it for the Fujitsu +MB86934 chip, which is the more recent SPARClite with FPU. + +With @option{-mcpu=sparclet}, GCC generates code for the SPARClet variant of +the SPARC architecture. This adds the integer multiply, multiply/accumulate, +integer divide step and scan (@code{ffs}) instructions which exist in SPARClet +but not in SPARC-V7. With @option{-mcpu=tsc701}, the compiler additionally +optimizes it for the TEMIC SPARClet chip. + +With @option{-mcpu=v9}, GCC generates code for the V9 variant of the SPARC +architecture. This adds 64-bit integer and floating-point move instructions, +3 additional floating-point condition code registers and conditional move +instructions. With @option{-mcpu=ultrasparc}, the compiler additionally +optimizes it for the Sun UltraSPARC I/II chips. With +@option{-mcpu=ultrasparc3}, the compiler additionally optimizes it for the +Sun UltraSPARC III chip. + @item -mtune=@var{cpu_type} @opindex mtune Set the instruction scheduling parameters for machine type @@ -5869,36 +6360,25 @@ that select a particular cpu implementation. Those are @samp{cypress}, @samp{sparclite86x}, @samp{tsc701}, @samp{ultrasparc}, and @samp{ultrasparc3}. +@item -mv8plus +@itemx -mno-v8plus +@opindex mv8plus +@opindex mno-v8plus +With @option{-mv8plus}, GCC generates code for the SPARC-V8+ ABI. The +difference from the V8 ABI is that the global and out registers are +considered 64-bit wide. This is enabled by default on Solaris in 32-bit +mode for all SPARC-V9 processors. + +@item -mvis +@itemx -mno-vis +@opindex mvis +@opindex mno-vis +With @option{-mvis}, GCC generates code that takes advantage of the UltraSPARC +Visual Instruction Set extensions. The default is @option{-mno-vis}. @end table -These @samp{-m} switches are supported in addition to the above -on the SPARCLET processor. - -@table @gcctabopt -@item -mlittle-endian -@opindex mlittle-endian -Generate code for a processor running in little-endian mode. - -@item -mlive-g0 -@opindex mlive-g0 -Treat register @code{%g0} as a normal register. -GCC will continue to clobber it as necessary but will not assume -it always reads as 0. - -@item -mbroken-saverestore -@opindex mbroken-saverestore -Generate code that does not use non-trivial forms of the @code{save} and -@code{restore} instructions. Early versions of the SPARCLET processor do -not correctly handle @code{save} and @code{restore} instructions used with -arguments. They correctly handle them used without arguments. A @code{save} -instruction used without arguments increments the current window pointer -but does not allocate a new stack frame. It is assumed that the window -overflow trap handler will properly handle this case as will interrupt -handlers. -@end table - -These @samp{-m} switches are supported in addition to the above -on SPARC V9 processors in 64-bit environments. +These @samp{-m} options are supported in addition to the above +on SPARC-V9 processors in 64-bit environments: @table @gcctabopt @item -mlittle-endian @@ -5917,31 +6397,31 @@ to 64 bits. @item -mcmodel=medlow @opindex mcmodel=medlow -Generate code for the Medium/Low code model: the program must be linked -in the low 32 bits of the address space. Pointers are 64 bits. -Programs can be statically or dynamically linked. +Generate code for the Medium/Low code model: 64-bit addresses, programs +must be linked in the low 32 bits of memory. Programs can be statically +or dynamically linked. @item -mcmodel=medmid @opindex mcmodel=medmid -Generate code for the Medium/Middle code model: the program must be linked -in the low 44 bits of the address space, the text segment must be less than -2G bytes, and data segment must be within 2G of the text segment. -Pointers are 64 bits. +Generate code for the Medium/Middle code model: 64-bit addresses, programs +must be linked in the low 44 bits of memory, the text and data segments must +be less than 2GB in size and the data segment must be located within 2GB of +the text segment. @item -mcmodel=medany @opindex mcmodel=medany -Generate code for the Medium/Anywhere code model: the program may be linked -anywhere in the address space, the text segment must be less than -2G bytes, and data segment must be within 2G of the text segment. -Pointers are 64 bits. +Generate code for the Medium/Anywhere code model: 64-bit addresses, programs +may be linked anywhere in memory, the text and data segments must be less +than 2GB in size and the data segment must be located within 2GB of the +text segment. @item -mcmodel=embmedany @opindex mcmodel=embmedany Generate code for the Medium/Anywhere code model for embedded systems: -assume a 32-bit text and a 32-bit data segment, both starting anywhere -(determined at link time). Register %g4 points to the base of the -data segment. Pointers are still 64 bits. -Programs are statically linked, PIC is not supported. +64-bit addresses, the text and data segments must be less than 2GB in +size, both starting anywhere in memory (determined at link time). The +global register %g4 points to the base of the data segment. Programs +are statically linked and PIC is not supported. @item -mstack-bias @itemx -mno-stack-bias @@ -5949,10 +6429,28 @@ Programs are statically linked, PIC is not supported. @opindex mno-stack-bias With @option{-mstack-bias}, GCC assumes that the stack pointer, and frame pointer if present, are offset by @minus{}2047 which must be added back -when making stack frame references. +when making stack frame references. This is the default in 64-bit mode. Otherwise, assume no such offset is present. @end table +These switches are supported in addition to the above on Solaris: + +@table @gcctabopt +@item -threads +@opindex threads +Add support for multithreading using the Solaris threads library. This +option sets flags for both the preprocessor and linker. This option does +not affect the thread safety of object code produced by the compiler or +that of libraries supplied with it. + +@item -pthreads +@opindex pthreads +Add support for multithreading using the POSIX threads library. This +option sets flags for both the preprocessor and linker. This option does +not affect the thread safety of object code produced by the compiler or +that of libraries supplied with it. +@end table + @node ARM Options @subsection ARM Options @cindex ARM options @@ -5977,15 +6475,19 @@ This is a synonym for @option{-mapcs-frame}. @opindex mapcs-26 Generate code for a processor running with a 26-bit program counter, and conforming to the function calling standards for the APCS 26-bit -option. This option replaces the @option{-m2} and @option{-m3} options -of previous releases of the compiler. +option. + +This option is deprecated. Future releases of the GCC will only support +generating code that runs in apcs-32 mode. @item -mapcs-32 @opindex mapcs-32 Generate code for a processor running with a 32-bit program counter, and conforming to the function calling standards for the APCS 32-bit -option. This option replaces the @option{-m6} option of previous releases -of the compiler. +option. + +This flag is deprecated. Future releases of GCC will make this flag +unconditional. @ignore @c not currently implemented @@ -6086,7 +6588,7 @@ synthesize the access as a series of byte accesses. The compiler can still use word accesses to load half-word data if it knows that the address is aligned to a word boundary. -This option is ignored when compiling for ARM architecture 4 or later, +This option has no effect when compiling for ARM architecture 4 or later, since these processors have instructions to directly access half-word objects in memory. @@ -6101,21 +6603,11 @@ Note that you cannot use this option to access unaligned word objects, since the processor will only fetch one 32-bit aligned object from memory. -The default setting for most targets is @option{-mno-alignment-traps}, since -this produces better code when there are no half-word memory -instructions available. +The default setting is @option{-malignment-traps}, since this produces +code that will also run on processors implementing ARM architecture +version 6 or later. -@item -mshort-load-bytes -@itemx -mno-short-load-words -@opindex mshort-load-bytes -@opindex mno-short-load-words -These are deprecated aliases for @option{-malignment-traps}. - -@item -mno-short-load-bytes -@itemx -mshort-load-words -@opindex mno-short-load-bytes -@opindex mshort-load-words -This are deprecated aliases for @option{-mno-alignment-traps}. +This option is deprecated and will be removed in the next release of GCC. @item -mcpu=@var{name} @opindex mcpu @@ -6129,8 +6621,10 @@ assembly code. Permissible names are: @samp{arm2}, @samp{arm250}, @samp{arm7500}, @samp{arm7500fe}, @samp{arm7tdmi}, @samp{arm8}, @samp{strongarm}, @samp{strongarm110}, @samp{strongarm1100}, @samp{arm8}, @samp{arm810}, @samp{arm9}, @samp{arm9e}, @samp{arm920}, -@samp{arm920t}, @samp{arm940t}, @samp{arm9tdmi}, @samp{arm10tdmi}, -@samp{arm1020t}, @samp{xscale}. +@samp{arm920t}, @samp{arm926ejs}, @samp{arm940t}, @samp{arm9tdmi}, +@samp{arm10tdmi}, @samp{arm1020t}, @samp{arm1026ejs}, +@samp{arm1136js}, @samp{arm1136jfs} ,@samp{xscale}, @samp{iwmmxt}, +@samp{ep9312}. @itemx -mtune=@var{name} @opindex mtune @@ -6150,7 +6644,8 @@ name to determine what kind of instructions it can emit when generating assembly code. This option can be used in conjunction with or instead of the @option{-mcpu=} option. Permissible names are: @samp{armv2}, @samp{armv2a}, @samp{armv3}, @samp{armv3m}, @samp{armv4}, @samp{armv4t}, -@samp{armv5}, @samp{armv5t}, @samp{armv5te}. +@samp{armv5}, @samp{armv5t}, @samp{armv5te}, @samp{armv6j}, +@samp{iwmmxt}, @samp{ep9312}. @item -mfpe=@var{number} @itemx -mfp=@var{number} @@ -6222,6 +6717,18 @@ before execution begins. Specify the register to be used for PIC addressing. The default is R10 unless stack-checking is enabled, when R9 is used. +@item -mcirrus-fix-invalid-insns +@opindex mcirrus-fix-invalid-insns +@opindex mno-cirrus-fix-invalid-insns +Insert NOPs into the instruction stream to in order to work around +problems with invalid Maverick instruction combinations. This option +is only valid if the @option{-mcpu=ep9312} option has been used to +enable generation of instructions for the Cirrus Maverick floating +point co-processor. This option is not enabled by default, since the +problem is only present in older Maverick implementations. The default +can be re-enabled by use of the @option{-mno-cirrus-fix-invalid-insns} +switch. + @item -mpoke-function-name @opindex mpoke-function-name Write the name of each function into the text section, directly @@ -6278,22 +6785,6 @@ of executing a function pointer if this option is enabled. @end table -@node MN10200 Options -@subsection MN10200 Options -@cindex MN10200 options - -These @option{-m} options are defined for Matsushita MN10200 architectures: -@table @gcctabopt - -@item -mrelax -@opindex mrelax -Indicate to the linker that it should perform a relaxation optimization pass -to shorten branches, calls and absolute memory addresses. This option only -has an effect when used on the command line for the final link step. - -This option makes symbolic debugging impossible. -@end table - @node MN10300 Options @subsection MN10300 Options @cindex MN10300 options @@ -6338,9 +6829,13 @@ This option makes symbolic debugging impossible. @subsection M32R/D Options @cindex M32R/D options -These @option{-m} options are defined for Mitsubishi M32R/D architectures: +These @option{-m} options are defined for Renesas M32R/D architectures: @table @gcctabopt +@item -m32r2 +@opindex m32r2 +Generate code for the M32R/2@. + @item -m32rx @opindex m32rx Generate code for the M32R/X@. @@ -6349,8 +6844,8 @@ Generate code for the M32R/X@. @opindex m32r Generate code for the M32R@. This is the default. -@item -mcode-model=small -@opindex mcode-model=small +@item -mmodel=small +@opindex mmodel=small Assume all objects live in the lower 16MB of memory (so that their addresses can be loaded with the @code{ld24} instruction), and assume all subroutines are reachable with the @code{bl} instruction. @@ -6359,14 +6854,14 @@ This is the default. The addressability of a particular object can be set with the @code{model} attribute. -@item -mcode-model=medium -@opindex mcode-model=medium +@item -mmodel=medium +@opindex mmodel=medium Assume objects may be anywhere in the 32-bit address space (the compiler will generate @code{seth/add3} instructions to load their addresses), and assume all subroutines are reachable with the @code{bl} instruction. -@item -mcode-model=large -@opindex mcode-model=large +@item -mmodel=large +@opindex mmodel=large Assume objects may be anywhere in the 32-bit address space (the compiler will generate @code{seth/add3} instructions to load their addresses), and assume subroutines may not be reachable with the @code{bl} instruction @@ -6408,237 +6903,51 @@ Compiling with different values of @var{num} may or may not work; if it doesn't the linker will give an error message---incorrect code will not be generated. -@end table - -@node M88K Options -@subsection M88K Options -@cindex M88k options - -These @samp{-m} options are defined for Motorola 88k architectures: - -@table @gcctabopt -@item -m88000 -@opindex m88000 -Generate code that works well on both the m88100 and the -m88110. - -@item -m88100 -@opindex m88100 -Generate code that works best for the m88100, but that also -runs on the m88110. - -@item -m88110 -@opindex m88110 -Generate code that works best for the m88110, and may not run -on the m88100. - -@item -mbig-pic -@opindex mbig-pic -Obsolete option to be removed from the next revision. -Use @option{-fPIC}. - -@item -midentify-revision -@opindex midentify-revision -@cindex identifying source, compiler (88k) -Include an @code{ident} directive in the assembler output recording the -source file name, compiler name and version, timestamp, and compilation -flags used. - -@item -mno-underscores -@opindex mno-underscores -@cindex underscores, avoiding (88k) -In assembler output, emit symbol names without adding an underscore -character at the beginning of each name. The default is to use an -underscore as prefix on each name. - -@item -mocs-debug-info -@itemx -mno-ocs-debug-info -@opindex mocs-debug-info -@opindex mno-ocs-debug-info -@cindex OCS (88k) -@cindex debugging, 88k OCS -Include (or omit) additional debugging information (about registers used -in each stack frame) as specified in the 88open Object Compatibility -Standard, ``OCS''@. This extra information allows debugging of code that -has had the frame pointer eliminated. The default for SVr4 and Delta 88 -SVr3.2 is to include this information; other 88k configurations omit this -information by default. - -@item -mocs-frame-position -@opindex mocs-frame-position -@cindex register positions in frame (88k) -When emitting COFF debugging information for automatic variables and -parameters stored on the stack, use the offset from the canonical frame -address, which is the stack pointer (register 31) on entry to the -function. The SVr4 and Delta88 SVr3.2, and BCS configurations use -@option{-mocs-frame-position}; other 88k configurations have the default -@option{-mno-ocs-frame-position}. - -@item -mno-ocs-frame-position -@opindex mno-ocs-frame-position -@cindex register positions in frame (88k) -When emitting COFF debugging information for automatic variables and -parameters stored on the stack, use the offset from the frame pointer -register (register 30). When this option is in effect, the frame -pointer is not eliminated when debugging information is selected by the --g switch. - -@item -moptimize-arg-area -@opindex moptimize-arg-area -@cindex arguments in frame (88k) -Save space by reorganizing the stack frame. This option generates code -that does not agree with the 88open specifications, but uses less -memory. - -@itemx -mno-optimize-arg-area -@opindex mno-optimize-arg-area -Do not reorganize the stack frame to save space. This is the default. -The generated conforms to the specification, but uses more memory. - -@item -mshort-data-@var{num} -@opindex mshort-data -@cindex smaller data references (88k) -@cindex r0-relative references (88k) -Generate smaller data references by making them relative to @code{r0}, -which allows loading a value using a single instruction (rather than the -usual two). You control which data references are affected by -specifying @var{num} with this option. For example, if you specify -@option{-mshort-data-512}, then the data references affected are those -involving displacements of less than 512 bytes. -@option{-mshort-data-@var{num}} is not effective for @var{num} greater -than 64k. - -@item -mserialize-volatile -@opindex mserialize-volatile -@itemx -mno-serialize-volatile -@opindex mno-serialize-volatile -@cindex sequential consistency on 88k -Do, or don't, generate code to guarantee sequential consistency -of volatile memory references. By default, consistency is -guaranteed. - -The order of memory references made by the MC88110 processor does -not always match the order of the instructions requesting those -references. In particular, a load instruction may execute before -a preceding store instruction. Such reordering violates -sequential consistency of volatile memory references, when there -are multiple processors. When consistency must be guaranteed, -GCC generates special instructions, as needed, to force -execution in the proper order. - -The MC88100 processor does not reorder memory references and so -always provides sequential consistency. However, by default, GCC -generates the special instructions to guarantee consistency -even when you use @option{-m88100}, so that the code may be run on an -MC88110 processor. If you intend to run your code only on the -MC88100 processor, you may use @option{-mno-serialize-volatile}. - -The extra code generated to guarantee consistency may affect the -performance of your application. If you know that you can safely -forgo this guarantee, you may use @option{-mno-serialize-volatile}. - -@item -msvr4 -@itemx -msvr3 -@opindex msvr4 -@opindex msvr3 -@cindex assembler syntax, 88k -@cindex SVr4 -Turn on (@option{-msvr4}) or off (@option{-msvr3}) compiler extensions -related to System V release 4 (SVr4). This controls the following: - -@enumerate -@item -Which variant of the assembler syntax to emit. -@item -@option{-msvr4} makes the C preprocessor recognize @samp{#pragma weak} -that is used on System V release 4. -@item -@option{-msvr4} makes GCC issue additional declaration directives used in -SVr4. -@end enumerate - -@option{-msvr4} is the default for the m88k-motorola-sysv4 configuration. -@option{-msvr3} is the default for all other m88k configurations. - -@item -mversion-03.00 -@opindex mversion-03.00 -This option is obsolete, and is ignored. -@c ??? which asm syntax better for GAS? option there too? - -@item -mno-check-zero-division -@itemx -mcheck-zero-division -@opindex mno-check-zero-division -@opindex mcheck-zero-division -@cindex zero division on 88k -Do, or don't, generate code to guarantee that integer division by -zero will be detected. By default, detection is guaranteed. - -Some models of the MC88100 processor fail to trap upon integer -division by zero under certain conditions. By default, when -compiling code that might be run on such a processor, GCC -generates code that explicitly checks for zero-valued divisors -and traps with exception number 503 when one is detected. Use of -@option{-mno-check-zero-division} suppresses such checking for code -generated to run on an MC88100 processor. - -GCC assumes that the MC88110 processor correctly detects all instances -of integer division by zero. When @option{-m88110} is specified, no -explicit checks for zero-valued divisors are generated, and both -@option{-mcheck-zero-division} and @option{-mno-check-zero-division} are -ignored. +@item -mdebug +@opindex mdebug +Makes the M32R specific code in the compiler display some statistics +that might help in debugging programs. + +@item -malign-loops +@opindex malign-loops +Align all loops to a 32-byte boundary. + +@item -mno-align-loops +@opindex mno-align-loops +Do not enforce a 32-byte alignment for loops. This is the default. + +@item -missue-rate=@var{number} +@opindex missue-rate=@var{number} +Issue @var{number} instructions per cycle. @var{number} can only be 1 +or 2. + +@item -mbranch-cost=@var{number} +@opindex mbranch-cost=@var{number} +@var{number} can only be 1 or 2. If it is 1 then branches will be +preferred over conditional code, if it is 2, then the opposite will +apply. + +@item -mflush-trap=@var{number} +@opindex mflush-trap=@var{number} +Specifies the trap number to use to flush the cache. The default is +12. Valid numbers are between 0 and 15 inclusive. + +@item -mno-flush-trap +@opindex mno-flush-trap +Specifies that the cache cannot be flushed by using a trap. + +@item -mflush-func=@var{name} +@opindex mflush-func=@var{name} +Specifies the name of the operating system function to call to flush +the cache. The default is @emph{_flush_cache}, but a function call +will only be used if a trap is not available. + +@item -mno-flush-func +@opindex mno-flush-func +Indicates that there is no OS function for flushing the cache. -@item -muse-div-instruction -@opindex muse-div-instruction -@cindex divide instruction, 88k -Use the div instruction for signed integer division on the -MC88100 processor. By default, the div instruction is not used. - -On the MC88100 processor the signed integer division instruction -div) traps to the operating system on a negative operand. The -operating system transparently completes the operation, but at a -large cost in execution time. By default, when compiling code -that might be run on an MC88100 processor, GCC emulates signed -integer division using the unsigned integer division instruction -divu), thereby avoiding the large penalty of a trap to the -operating system. Such emulation has its own, smaller, execution -cost in both time and space. To the extent that your code's -important signed integer division operations are performed on two -nonnegative operands, it may be desirable to use the div -instruction directly. - -On the MC88110 processor the div instruction (also known as the -divs instruction) processes negative operands without trapping to -the operating system. When @option{-m88110} is specified, -@option{-muse-div-instruction} is ignored, and the div instruction is used -for signed integer division. - -Note that the result of dividing @code{INT_MIN} by @minus{}1 is undefined. In -particular, the behavior of such a division with and without -@option{-muse-div-instruction} may differ. - -@item -mtrap-large-shift -@itemx -mhandle-large-shift -@opindex mtrap-large-shift -@opindex mhandle-large-shift -@cindex bit shift overflow (88k) -@cindex large bit shifts (88k) -Include code to detect bit-shifts of more than 31 bits; respectively, -trap such shifts or emit code to handle them properly. By default GCC -makes no special provision for large bit shifts. - -@item -mwarn-passed-structs -@opindex mwarn-passed-structs -@cindex structure passing (88k) -Warn when a function passes a struct as an argument or result. -Structure-passing conventions have changed during the evolution of the C -language, and are often the source of portability problems. By default, -GCC issues no such warning. @end table -@c break page here to avoid unsightly interparagraph stretch. -@c -zw, 2001-8-17 -@page - @node RS/6000 and PowerPC Options @subsection IBM RS/6000 and PowerPC Options @cindex RS/6000 and PowerPC Options @@ -6736,12 +7045,15 @@ should normally not specify either @option{-mnew-mnemonics} or @opindex mcpu Set architecture type, register usage, choice of mnemonics, and instruction scheduling parameters for machine type @var{cpu_type}. -Supported values for @var{cpu_type} are @samp{rios}, @samp{rios1}, -@samp{rsc}, @samp{rios2}, @samp{rs64a}, @samp{601}, @samp{602}, -@samp{603}, @samp{603e}, @samp{604}, @samp{604e}, @samp{620}, -@samp{630}, @samp{740}, @samp{7400}, @samp{7450}, @samp{750}, -@samp{power}, @samp{power2}, @samp{powerpc}, @samp{403}, @samp{505}, -@samp{801}, @samp{821}, @samp{823}, and @samp{860} and @samp{common}. +Supported values for @var{cpu_type} are @samp{401}, @samp{403}, +@samp{405}, @samp{405fp}, @samp{440}, @samp{440fp}, @samp{505}, +@samp{601}, @samp{602}, @samp{603}, @samp{603e}, @samp{604}, +@samp{604e}, @samp{620}, @samp{630}, @samp{740}, @samp{7400}, +@samp{7450}, @samp{750}, @samp{801}, @samp{821}, @samp{823}, +@samp{860}, @samp{970}, @samp{common}, @samp{ec603e}, @samp{G3}, +@samp{G4}, @samp{G5}, @samp{power}, @samp{power2}, @samp{power3}, +@samp{power4}, @samp{power5}, @samp{powerpc}, @samp{powerpc64}, +@samp{rios}, @samp{rios1}, @samp{rios2}, @samp{rsc}, and @samp{rs64a}. @option{-mcpu=common} selects a completely generic processor. Code generated under this option will run on any POWER or PowerPC processor. @@ -6759,43 +7071,23 @@ The other options specify a specific processor. Code generated under those options will run best on that processor, and may not run at all on others. -The @option{-mcpu} options automatically enable or disable other -@option{-m} options as follows: - -@table @samp -@item common -@option{-mno-power}, @option{-mno-powerpc} - -@item power -@itemx power2 -@itemx rios1 -@itemx rios2 -@itemx rsc -@option{-mpower}, @option{-mno-powerpc}, @option{-mno-new-mnemonics} - -@item powerpc -@itemx rs64a -@itemx 602 -@itemx 603 -@itemx 603e -@itemx 604 -@itemx 620 -@itemx 630 -@itemx 740 -@itemx 7400 -@itemx 7450 -@itemx 750 -@itemx 505 -@option{-mno-power}, @option{-mpowerpc}, @option{-mnew-mnemonics} - -@item 601 -@option{-mpower}, @option{-mpowerpc}, @option{-mnew-mnemonics} - -@item 403 -@itemx 821 -@itemx 860 -@option{-mno-power}, @option{-mpowerpc}, @option{-mnew-mnemonics}, @option{-msoft-float} -@end table +The @option{-mcpu} options automatically enable or disable the +following options: @option{-maltivec}, @option{-mhard-float}, +@option{-mmfcrf}, @option{-mmultiple}, @option{-mnew-mnemonics}, +@option{-mpower}, @option{-mpower2}, @option{-mpowerpc64}, +@option{-mpowerpc-gpopt}, @option{-mpowerpc-gfxopt}, +@option{-mstring}. The particular options set for any particular CPU +will vary between compiler versions, depending on what setting seems +to produce optimal code for that CPU; it doesn't necessarily reflect +the actual hardware's capabilities. If you wish to set an individual +option to a particular value, you may specify it after the +@option{-mcpu} option, like @samp{-mcpu=970 -mno-altivec}. + +On AIX, the @option{-maltivec} and @option{-mpowerpc64} options are +not enabled or disabled by the @option{-mcpu} option at present, since +AIX does not have full support for these options. You may still +enable or disable them individually if you're sure it'll work in your +environment. @item -mtune=@var{cpu_type} @opindex mtune @@ -6831,6 +7123,19 @@ Disable Booke SPE ABI extensions for the current ABI. @opindex misel This switch enables or disables the generation of ISEL instructions. +@item -mspe=@var{yes/no} +@itemx -mspe +@opindex mspe +This switch enables or disables the generation of SPE simd +instructions. + +@item -mfloat-gprs=@var{yes/no} +@itemx -mfloat-gprs +@opindex mfloat-gprs +This switch enables or disables the generation of floating point +operations on the general purpose registers for architectures that +support it. This option is currently only available on the MPC8540. + @item -mfull-toc @itemx -mno-fp-in-toc @itemx -mno-sum-in-toc @@ -6900,6 +7205,16 @@ appropriate directory location. The Parallel Environment does not support threads, so the @option{-mpe} option and the @option{-pthread} option are incompatible. +@item -malign-natural +@itemx -malign-power +@opindex malign-natural +@opindex malign-power +On AIX, Darwin, and 64-bit PowerPC GNU/Linux, the option +@option{-malign-natural} overrides the ABI-defined alignment of larger +types, such as floating-point doubles, on their natural size-based boundary. +The option @option{-malign-power} instructs GCC to follow the ABI-specified +alignment rules. GCC defaults to the standard alignment defined in the ABI. + @item -msoft-float @itemx -mhard-float @opindex msoft-float @@ -7017,6 +7332,46 @@ On System V.4 and embedded PowerPC systems compile code for the processor in big endian mode. The @option{-mbig-endian} option is the same as @option{-mbig}. +@item -mdynamic-no-pic +@opindex mdynamic-no-pic +On Darwin and Mac OS X systems, compile code so that it is not +relocatable, but that its external references are relocatable. The +resulting code is suitable for applications, but not shared +libraries. + +@item -mprioritize-restricted-insns=@var{priority} +@opindex mprioritize-restricted-insns +This option controls the priority that is assigned to +dispatch-slot restricted instructions during the second scheduling +pass. The argument @var{priority} takes the value @var{0/1/2} to assign +@var{no/highest/second-highest} priority to dispatch slot restricted +instructions. + +@item -msched-costly-dep=@var{dependence_type} +@opindex msched-costly-dep +This option controls which dependences are considered costly +by the target during instruction scheduling. The argument +@var{dependence_type} takes one of the following values: +@var{no}: no dependence is costly, +@var{all}: all dependences are costly, +@var{true_store_to_load}: a true dependence from store to load is costly, +@var{store_to_load}: any dependence from store to load is costly, +@var{number}: any dependence which latency >= @var{number} is costly. + +@item -minsert-sched-nops=@var{scheme} +@opindex minsert-sched-nops +This option controls which nop insertion scheme will be used during +the second scheduling pass. The argument @var{scheme} takes one of the +following values: +@var{no}: Don't insert nops. +@var{pad}: Pad with nops any dispatch group which has vacant issue slots, +according to the scheduler's grouping. +@var{regroup_exact}: Insert nops to force costly dependent insns into +separate groups. Insert exactly as many nops as needed to force an insn +to a new group, according to the estimated processor grouping. +@var{number}: Insert nops to force costly dependent insns into +separate groups. Insert @var{number} nops to force an insn to a new group. + @item -mcall-sysv @opindex mcall-sysv On System V.4 and embedded PowerPC systems compile code using calling @@ -7032,12 +7387,6 @@ Specify both @option{-mcall-sysv} and @option{-meabi} options. @opindex mcall-sysv-noeabi Specify both @option{-mcall-sysv} and @option{-mno-eabi} options. -@item -mcall-aix -@opindex mcall-aix -On System V.4 and embedded PowerPC systems compile code using calling -conventions that are similar to those used on AIX@. This is the -default if you configured GCC using @samp{powerpc-*-eabiaix}. - @item -mcall-solaris @opindex mcall-solaris On System V.4 and embedded PowerPC systems compile code for the Solaris @@ -7223,6 +7572,10 @@ generate slower code. As of this writing, the AIX linker can do this, as can the GNU linker for PowerPC/64. It is planned to add this feature to the GNU linker for 32-bit PowerPC systems as well. +On Mach-O (Darwin) systems, this option directs the compiler emit to +the glue for every direct call, and the Darwin linker decides whether +to use or discard it. + In the future, we may cause GCC to ignore all longcall specifications when the linker is known to generate glue. @@ -7241,8 +7594,8 @@ These options are defined for all architectures running the Darwin operating system. They are useful for compatibility with other Mac OS compilers. @table @gcctabopt -@item -all_load -@opindex all_load +@item -all_load +@opindex all_load Loads all members of static archive libraries. See man ld(1) for more information. @@ -7256,7 +7609,7 @@ to be fatal. Causes the output file to be marked such that the dynamic linker will bind all undefined references when the file is loaded or launched. -@item -bundle +@item -bundle @opindex bundle Produce a Mach-o bundle format file. See man ld(1) for more information. @@ -7267,64 +7620,65 @@ This specifies the @var{executable} that will be loading the build output file being linked. See man ld(1) for more information. @item -allowable_client @var{client_name} -@item -arch_only - -@item -client_name -@item -compatibility_version -@item -current_version -@item -dependency-file -@item -dylib_file -@item -dylinker_install_name -@item -dynamic -@item -dynamiclib -@item -exported_symbols_list -@item -filelist -@item -flat_namespace -@item -force_cpusubtype_ALL -@item -force_flat_namespace -@item -headerpad_max_install_names -@item -image_base -@item -init -@item -install_name -@item -keep_private_externs -@item -multi_module -@item -multiply_defined -@item -multiply_defined_unused -@item -noall_load -@item -nomultidefs -@item -noprebind -@item -noseglinkedit -@item -pagezero_size -@item -prebind -@item -prebind_all_twolevel_modules -@item -private_bundle -@item -read_only_relocs -@item -sectalign -@item -sectobjectsymbols -@item -whyload -@item -seg1addr -@item -sectcreate -@item -sectobjectsymbols -@item -sectorder -@item -seg_addr_table -@item -seg_addr_table_filename -@item -seglinkedit -@item -segprot -@item -segs_read_only_addr -@item -segs_read_write_addr -@item -single_module -@item -static -@item -sub_library -@item -sub_umbrella -@item -twolevel_namespace -@item -umbrella -@item -undefined -@item -unexported_symbols_list -@item -weak_reference_mismatches -@item -whatsloaded +@itemx -arch_only + +@itemx -client_name +@itemx -compatibility_version +@itemx -current_version +@itemx -dependency-file +@itemx -dylib_file +@itemx -dylinker_install_name +@itemx -dynamic +@itemx -dynamiclib +@itemx -exported_symbols_list +@itemx -filelist +@itemx -flat_namespace +@itemx -force_cpusubtype_ALL +@itemx -force_flat_namespace +@itemx -headerpad_max_install_names +@itemx -image_base +@itemx -init +@itemx -install_name +@itemx -keep_private_externs +@itemx -multi_module +@itemx -multiply_defined +@itemx -multiply_defined_unused +@itemx -noall_load +@itemx -nofixprebinding +@itemx -nomultidefs +@itemx -noprebind +@itemx -noseglinkedit +@itemx -pagezero_size +@itemx -prebind +@itemx -prebind_all_twolevel_modules +@itemx -private_bundle +@itemx -read_only_relocs +@itemx -sectalign +@itemx -sectobjectsymbols +@itemx -whyload +@itemx -seg1addr +@itemx -sectcreate +@itemx -sectobjectsymbols +@itemx -sectorder +@itemx -seg_addr_table +@itemx -seg_addr_table_filename +@itemx -seglinkedit +@itemx -segprot +@itemx -segs_read_only_addr +@itemx -segs_read_write_addr +@itemx -single_module +@itemx -static +@itemx -sub_library +@itemx -sub_umbrella +@itemx -twolevel_namespace +@itemx -umbrella +@itemx -undefined +@itemx -unexported_symbols_list +@itemx -weak_reference_mismatches +@itemx -whatsloaded @opindex allowable_client -@opindex arch_only +@opindex arch_only @opindex client_name @opindex compatibility_version @opindex current_version @@ -7334,34 +7688,35 @@ output file being linked. See man ld(1) for more information. @opindex dynamic @opindex dynamiclib @opindex exported_symbols_list -@opindex filelist -@opindex flat_namespace +@opindex filelist +@opindex flat_namespace @opindex force_cpusubtype_ALL @opindex force_flat_namespace @opindex headerpad_max_install_names @opindex image_base -@opindex init +@opindex init @opindex install_name @opindex keep_private_externs -@opindex multi_module +@opindex multi_module @opindex multiply_defined -@opindex multiply_defined_unused -@opindex noall_load -@opindex nomultidefs +@opindex multiply_defined_unused +@opindex noall_load +@opindex nofixprebinding +@opindex nomultidefs @opindex noprebind -@opindex noseglinkedit +@opindex noseglinkedit @opindex pagezero_size @opindex prebind @opindex prebind_all_twolevel_modules -@opindex private_bundle +@opindex private_bundle @opindex read_only_relocs -@opindex sectalign -@opindex sectobjectsymbols -@opindex whyload +@opindex sectalign +@opindex sectobjectsymbols +@opindex whyload @opindex seg1addr -@opindex sectcreate -@opindex sectobjectsymbols -@opindex sectorder +@opindex sectcreate +@opindex sectobjectsymbols +@opindex sectorder @opindex seg_addr_table @opindex seg_addr_table_filename @opindex seglinkedit @@ -7379,85 +7734,44 @@ output file being linked. See man ld(1) for more information. @opindex weak_reference_mismatches @opindex whatsloaded -This options are available for Darwin linker. Darwin linker man page +These options are available for Darwin linker. Darwin linker man page describes them in detail. @end table -@node RT Options -@subsection IBM RT Options -@cindex RT options -@cindex IBM RT options - -These @samp{-m} options are defined for the IBM RT PC: - -@table @gcctabopt -@item -min-line-mul -@opindex min-line-mul -Use an in-line code sequence for integer multiplies. This is the -default. - -@item -mcall-lib-mul -@opindex mcall-lib-mul -Call @code{lmul$$} for integer multiples. - -@item -mfull-fp-blocks -@opindex mfull-fp-blocks -Generate full-size floating point data blocks, including the minimum -amount of scratch space recommended by IBM@. This is the default. - -@item -mminimum-fp-blocks -@opindex mminimum-fp-blocks -Do not include extra scratch space in floating point data blocks. This -results in smaller code, but slower execution, since scratch space must -be allocated dynamically. - -@cindex @file{stdarg.h} and RT PC -@item -mfp-arg-in-fpregs -@opindex mfp-arg-in-fpregs -Use a calling sequence incompatible with the IBM calling convention in -which floating point arguments are passed in floating point registers. -Note that @code{stdarg.h} will not work with floating point operands -if this option is specified. - -@item -mfp-arg-in-gregs -@opindex mfp-arg-in-gregs -Use the normal calling convention for floating point arguments. This is -the default. - -@item -mhc-struct-return -@opindex mhc-struct-return -Return structures of more than one word in memory, rather than in a -register. This provides compatibility with the MetaWare HighC (hc) -compiler. Use the option @option{-fpcc-struct-return} for compatibility -with the Portable C Compiler (pcc). - -@item -mnohc-struct-return -@opindex mnohc-struct-return -Return some structures of more than one word in registers, when -convenient. This is the default. For compatibility with the -IBM-supplied compilers, use the option @option{-fpcc-struct-return} or the -option @option{-mhc-struct-return}. -@end table - @node MIPS Options @subsection MIPS Options @cindex MIPS options -These @samp{-m} options are defined for the MIPS family of computers: - @table @gcctabopt +@item -EB +@opindex EB +Generate big-endian code. + +@item -EL +@opindex EL +Generate little-endian code. This is the default for @samp{mips*el-*-*} +configurations. + @item -march=@var{arch} @opindex march Generate code that will run on @var{arch}, which can be the name of a -generic MIPS ISA, or the name of a particular processor. The ISA names -are: @samp{mips1}, @samp{mips2}, @samp{mips3}, @samp{mips4}, @samp{mips32} -and @samp{mips64}. The processor names are: @samp{r2000}, -@samp{r3000}, @samp{r3900}, @samp{r4000}, @samp{vr4100}, @samp{vr4300}, -@samp{r4400}, @samp{r4600}, @samp{r4650}, @samp{vr5000}, @samp{r6000}, -@samp{r8000}, @samp{4kc}, @samp{4kp}, @samp{5kc}, @samp{20kc}, -@samp{orion}, and @samp{sb1}. The special value @samp{from-abi} selects the +generic MIPS ISA, or the name of a particular processor. +The ISA names are: +@samp{mips1}, @samp{mips2}, @samp{mips3}, @samp{mips4}, +@samp{mips32}, @samp{mips32r2}, and @samp{mips64}. +The processor names are: +@samp{4kc}, @samp{4kp}, @samp{5kc}, @samp{20kc}, +@samp{m4k}, +@samp{r2000}, @samp{r3000}, @samp{r3900}, @samp{r4000}, @samp{r4400}, +@samp{r4600}, @samp{r4650}, @samp{r6000}, @samp{r8000}, @samp{rm7000}, +@samp{rm9000}, +@samp{orion}, +@samp{sb1}, +@samp{vr4100}, @samp{vr4111}, @samp{vr4120}, @samp{vr4300}, +@samp{vr5000}, @samp{vr5400} and @samp{vr5500}. +The special value @samp{from-abi} selects the most compatible architecture for the selected ABI (that is, @samp{mips1} for 32-bit ABIs and @samp{mips3} for 64-bit ABIs)@. @@ -7516,289 +7830,268 @@ Equivalent to @samp{-march=mips4}. @opindex mips32 Equivalent to @samp{-march=mips32}. +@item -mips32r2 +@opindex mips32r2 +Equivalent to @samp{-march=mips32r2}. + @item -mips64 @opindex mips64 Equivalent to @samp{-march=mips64}. -@item -mfused-madd -@itemx -mno-fused-madd -@opindex mfused-madd -@opindex mno-fused-madd -Generate code that uses (does not use) the floating point multiply and -accumulate instructions, when they are available. These instructions -are generated by default if they are available, but this may be -undesirable if the extra precision causes problems or on certain chips -in the mode where denormals are rounded to zero where denormals -generated by multiply and accumulate instructions cause exceptions -anyway. +@item -mips16 +@itemx -mno-mips16 +@opindex mips16 +@opindex mno-mips16 +Use (do not use) the MIPS16 ISA. -@item -mfp32 -@opindex mfp32 -Assume that floating point registers are 32 bits wide. +@item -mabi=32 +@itemx -mabi=o64 +@itemx -mabi=n32 +@itemx -mabi=64 +@itemx -mabi=eabi +@opindex mabi=32 +@opindex mabi=o64 +@opindex mabi=n32 +@opindex mabi=64 +@opindex mabi=eabi +Generate code for the given ABI@. -@item -mfp64 -@opindex mfp64 -Assume that floating point registers are 64 bits wide. +Note that the EABI has a 32-bit and a 64-bit variant. GCC normally +generates 64-bit code when you select a 64-bit architecture, but you +can use @option{-mgp32} to get 32-bit code instead. + +@item -mabicalls +@itemx -mno-abicalls +@opindex mabicalls +@opindex mno-abicalls +Generate (do not generate) SVR4-style position-independent code. +@option{-mabicalls} is the default for SVR4-based systems. + +@item -mxgot +@itemx -mno-xgot +@opindex mxgot +@opindex mno-xgot +Lift (do not lift) the usual restrictions on the size of the global +offset table. + +GCC normally uses a single instruction to load values from the GOT. +While this is relatively efficient, it will only work if the GOT +is smaller than about 64k. Anything larger will cause the linker +to report an error such as: + +@cindex relocation truncated to fit (MIPS) +@smallexample +relocation truncated to fit: R_MIPS_GOT16 foobar +@end smallexample + +If this happens, you should recompile your code with @option{-mxgot}. +It should then work with very large GOTs, although it will also be +less efficient, since it will take three instructions to fetch the +value of a global symbol. + +Note that some linkers can create multiple GOTs. If you have such a +linker, you should only need to use @option{-mxgot} when a single object +file accesses more than 64k's worth of GOT entries. Very few do. + +These options have no effect unless GCC is generating position +independent code. + +@item -membedded-pic +@itemx -mno-embedded-pic +@opindex membedded-pic +@opindex mno-embedded-pic +Generate (do not generate) position-independent code suitable for some +embedded systems. All calls are made using PC relative addresses, and +all data is addressed using the $gp register. No more than 65536 +bytes of global data may be used. This requires GNU as and GNU ld, +which do most of the work. @item -mgp32 @opindex mgp32 -Assume that general purpose registers are 32 bits wide. +Assume that general-purpose registers are 32 bits wide. @item -mgp64 @opindex mgp64 -Assume that general purpose registers are 64 bits wide. +Assume that general-purpose registers are 64 bits wide. + +@item -mfp32 +@opindex mfp32 +Assume that floating-point registers are 32 bits wide. + +@item -mfp64 +@opindex mfp64 +Assume that floating-point registers are 64 bits wide. + +@item -mhard-float +@opindex mhard-float +Use floating-point coprocessor instructions. + +@item -msoft-float +@opindex msoft-float +Do not use floating-point coprocessor instructions. Implement +floating-point calculations using library calls instead. + +@item -msingle-float +@opindex msingle-float +Assume that the floating-point coprocessor only supports single-precision +operations. + +@itemx -mdouble-float +@opindex mdouble-float +Assume that the floating-point coprocessor supports double-precision +operations. This is the default. @item -mint64 @opindex mint64 -Force int and long types to be 64 bits wide. See @option{-mlong32} for an -explanation of the default, and the width of pointers. +Force @code{int} and @code{long} types to be 64 bits wide. See +@option{-mlong32} for an explanation of the default and the way +that the pointer size is determined. @item -mlong64 @opindex mlong64 -Force long types to be 64 bits wide. See @option{-mlong32} for an -explanation of the default, and the width of pointers. +Force @code{long} types to be 64 bits wide. See @option{-mlong32} for +an explanation of the default and the way that the pointer size is +determined. @item -mlong32 @opindex mlong32 -Force long, int, and pointer types to be 32 bits wide. +Force @code{long}, @code{int}, and pointer types to be 32 bits wide. -The default size of ints, longs and pointers depends on the ABI@. All -the supported ABIs use 32-bit ints. The n64 ABI uses 64-bit longs, as -does the 64-bit Cygnus EABI; the others use 32-bit longs. Pointers -are the same size as longs, or the same size as integer registers, -whichever is smaller. +The default size of @code{int}s, @code{long}s and pointers depends on +the ABI@. All the supported ABIs use 32-bit @code{int}s. The n64 ABI +uses 64-bit @code{long}s, as does the 64-bit EABI; the others use +32-bit @code{long}s. Pointers are the same size as @code{long}s, +or the same size as integer registers, whichever is smaller. -@item -mabi=32 -@itemx -mabi=o64 -@itemx -mabi=n32 -@itemx -mabi=64 -@itemx -mabi=eabi -@itemx -mabi=meabi -@opindex mabi=32 -@opindex mabi=o64 -@opindex mabi=n32 -@opindex mabi=64 -@opindex mabi=eabi -@opindex mabi=meabi -Generate code for the given ABI@. +@item -G @var{num} +@opindex G +@cindex smaller data references (MIPS) +@cindex gp-relative references (MIPS) +Put global and static items less than or equal to @var{num} bytes into +the small data or bss section instead of the normal data or bss section. +This allows the data to be accessed using a single instruction. -Note that there are two embedded ABIs: @option{-mabi=eabi} -selects the one defined by Cygnus while @option{-meabi=meabi} -selects the one defined by MIPS@. Both these ABIs have -32-bit and 64-bit variants. Normally, GCC will generate -64-bit code when you select a 64-bit architecture, but you -can use @option{-mgp32} to get 32-bit code instead. +All modules should be compiled with the same @option{-G @var{num}} +value. -@item -mmips-as -@opindex mmips-as -Generate code for the MIPS assembler, and invoke @file{mips-tfile} to -add normal debug information. This is the default for all -platforms except for the OSF/1 reference platform, using the OSF/rose -object format. If the either of the @option{-gstabs} or @option{-gstabs+} -switches are used, the @file{mips-tfile} program will encapsulate the -stabs within MIPS ECOFF@. +@item -membedded-data +@itemx -mno-embedded-data +@opindex membedded-data +@opindex mno-embedded-data +Allocate variables to the read-only data section first if possible, then +next in the small data section if possible, otherwise in data. This gives +slightly slower code than the default, but reduces the amount of RAM required +when executing, and thus may be preferred for some embedded systems. -@item -mgas -@opindex mgas -Generate code for the GNU assembler. This is the default on the OSF/1 -reference platform, using the OSF/rose object format. Also, this is -the default if the configure option @option{--with-gnu-as} is used. +@item -muninit-const-in-rodata +@itemx -mno-uninit-const-in-rodata +@opindex muninit-const-in-rodata +@opindex mno-uninit-const-in-rodata +Put uninitialized @code{const} variables in the read-only data section. +This option is only meaningful in conjunction with @option{-membedded-data}. @item -msplit-addresses @itemx -mno-split-addresses @opindex msplit-addresses @opindex mno-split-addresses -Generate code to load the high and low parts of address constants separately. -This allows GCC to optimize away redundant loads of the high order -bits of addresses. This optimization requires GNU as and GNU ld. -This optimization is enabled by default for some embedded targets where -GNU as and GNU ld are standard. +Enable (disable) use of the @code{%hi()} and @code{%lo()} assembler +relocation operators. This option has been superceded by +@option{-mexplicit-relocs} but is retained for backwards compatibility. + +@item -mexplicit-relocs +@itemx -mno-explicit-relocs +@opindex mexplicit-relocs +@opindex mno-explicit-relocs +Use (do not use) assembler relocation operators when dealing with symbolic +addresses. The alternative, selected by @option{-mno-explicit-relocs}, +is to use assembler macros instead. + +@option{-mexplicit-relocs} is usually the default if GCC was +configured to use an assembler that supports relocation operators. +However, there are two exceptions: + +@itemize @bullet +@item +GCC is not yet able to generate explicit relocations for the combination +of @option{-mabi=64} and @option{-mno-abicalls}. This will be addressed +in a future release. + +@item +The combination of @option{-mabicalls} and @option{-fno-unit-at-a-time} +implies @option{-mno-explicit-relocs} unless explicitly overridden. +This is because, when generating abicalls, the choice of relocation +depends on whether a symbol is local or global. In some rare cases, +GCC will not be able to decide this until the whole compilation unit +has been read. +@end itemize @item -mrnames @itemx -mno-rnames @opindex mrnames @opindex mno-rnames -The @option{-mrnames} switch says to output code using the MIPS software -names for the registers, instead of the hardware names (ie, @var{a0} -instead of @var{$4}). The only known assembler that supports this option -is the Algorithmics assembler. - -@item -mgpopt -@itemx -mno-gpopt -@opindex mgpopt -@opindex mno-gpopt -The @option{-mgpopt} switch says to write all of the data declarations -before the instructions in the text section, this allows the MIPS -assembler to generate one word memory references instead of using two -words for short global or static data items. This is on by default if -optimization is selected. - -@item -mstats -@itemx -mno-stats -@opindex mstats -@opindex mno-stats -For each non-inline function processed, the @option{-mstats} switch -causes the compiler to emit one line to the standard error file to -print statistics about the program (number of registers saved, stack -size, etc.). +Generate (do not generate) code that refers to registers using their +software names. The default is @option{-mno-rnames}, which tells GCC +to use hardware names like @samp{$4} instead of software names like +@samp{a0}. The only assembler known to support @option{-rnames} is +the Algorithmics assembler. + +@item -mcheck-zero-division +@itemx -mno-check-zero-division +@opindex mcheck-zero-division +@opindex mno-check-zero-division +Trap (do not trap) on integer division by zero. The default is +@option{-mcheck-zero-division}. @item -mmemcpy @itemx -mno-memcpy @opindex mmemcpy @opindex mno-memcpy -The @option{-mmemcpy} switch makes all block moves call the appropriate -string function (@samp{memcpy} or @samp{bcopy}) instead of possibly -generating inline code. - -@item -mmips-tfile -@itemx -mno-mips-tfile -@opindex mmips-tfile -@opindex mno-mips-tfile -The @option{-mno-mips-tfile} switch causes the compiler not -postprocess the object file with the @file{mips-tfile} program, -after the MIPS assembler has generated it to add debug support. If -@file{mips-tfile} is not run, then no local variables will be -available to the debugger. In addition, @file{stage2} and -@file{stage3} objects will have the temporary file names passed to the -assembler embedded in the object file, which means the objects will -not compare the same. The @option{-mno-mips-tfile} switch should only -be used when there are bugs in the @file{mips-tfile} program that -prevents compilation. - -@item -msoft-float -@opindex msoft-float -Generate output containing library calls for floating point. -@strong{Warning:} the requisite libraries are not part of GCC@. -Normally the facilities of the machine's usual C compiler are used, but -this can't be done directly in cross-compilation. You must make your -own arrangements to provide suitable library functions for -cross-compilation. - -@item -mhard-float -@opindex mhard-float -Generate output containing floating point instructions. This is the -default if you use the unmodified sources. - -@item -mabicalls -@itemx -mno-abicalls -@opindex mabicalls -@opindex mno-abicalls -Emit (or do not emit) the pseudo operations @samp{.abicalls}, -@samp{.cpload}, and @samp{.cprestore} that some System V.4 ports use for -position independent code. +Force (do not force) the use of @code{memcpy()} for non-trivial block +moves. The default is @option{-mno-memcpy}, which allows GCC to inline +most constant-sized copies. @item -mlong-calls @itemx -mno-long-calls @opindex mlong-calls @opindex mno-long-calls -Do all calls with the @samp{JALR} instruction, which requires -loading up a function's address into a register before the call. -You need to use this switch, if you call outside of the current -512 megabyte segment to functions that are not through pointers. - -@item -mhalf-pic -@itemx -mno-half-pic -@opindex mhalf-pic -@opindex mno-half-pic -Put pointers to extern references into the data section and load them -up, rather than put the references in the text section. +Disable (do not disable) use of the @code{jal} instruction. Calling +functions using @code{jal} is more efficient but requires the caller +and callee to be in the same 256 megabyte segment. -@item -membedded-pic -@itemx -mno-embedded-pic -@opindex membedded-pic -@opindex mno-embedded-pic -Generate PIC code suitable for some embedded systems. All calls are -made using PC relative address, and all data is addressed using the $gp -register. No more than 65536 bytes of global data may be used. This -requires GNU as and GNU ld which do most of the work. This currently -only works on targets which use ECOFF; it does not work with ELF@. - -@item -membedded-data -@itemx -mno-embedded-data -@opindex membedded-data -@opindex mno-embedded-data -Allocate variables to the read-only data section first if possible, then -next in the small data section if possible, otherwise in data. This gives -slightly slower code than the default, but reduces the amount of RAM required -when executing, and thus may be preferred for some embedded systems. - -@item -muninit-const-in-rodata -@itemx -mno-uninit-const-in-rodata -@opindex muninit-const-in-rodata -@opindex mno-uninit-const-in-rodata -When used together with @option{-membedded-data}, it will always store uninitialized -const variables in the read-only data section. - -@item -msingle-float -@itemx -mdouble-float -@opindex msingle-float -@opindex mdouble-float -The @option{-msingle-float} switch tells gcc to assume that the floating -point coprocessor only supports single precision operations, as on the -@samp{r4650} chip. The @option{-mdouble-float} switch permits gcc to use -double precision operations. This is the default. +This option has no effect on abicalls code. The default is +@option{-mno-long-calls}. @item -mmad @itemx -mno-mad @opindex mmad @opindex mno-mad -Permit use of the @samp{mad}, @samp{madu} and @samp{mul} instructions, -as on the @samp{r4650} chip. - -@item -m4650 -@opindex m4650 -Turns on @option{-msingle-float}, @option{-mmad}, and, at least for now, -@option{-mcpu=r4650}. - -@item -mips16 -@itemx -mno-mips16 -@opindex mips16 -@opindex mno-mips16 -Enable 16-bit instructions. +Enable (disable) use of the @code{mad}, @code{madu} and @code{mul} +instructions, as provided by the R4650 ISA. -@item -mentry -@opindex mentry -Use the entry and exit pseudo ops. This option can only be used with -@option{-mips16}. - -@item -EL -@opindex EL -Compile code for the processor in little endian mode. -The requisite libraries are assumed to exist. - -@item -EB -@opindex EB -Compile code for the processor in big endian mode. -The requisite libraries are assumed to exist. +@item -mfused-madd +@itemx -mno-fused-madd +@opindex mfused-madd +@opindex mno-fused-madd +Enable (disable) use of the floating point multiply-accumulate +instructions, when they are available. The default is +@option{-mfused-madd}. -@item -G @var{num} -@opindex G -@cindex smaller data references (MIPS) -@cindex gp-relative references (MIPS) -Put global and static items less than or equal to @var{num} bytes into -the small data or bss sections instead of the normal data or bss -section. This allows the assembler to emit one word memory reference -instructions based on the global pointer (@var{gp} or @var{$28}), -instead of the normal two words used. By default, @var{num} is 8 when -the MIPS assembler is used, and 0 when the GNU assembler is used. The -@option{-G @var{num}} switch is also passed to the assembler and linker. -All modules should be compiled with the same @option{-G @var{num}} -value. +When multiply-accumulate instructions are used, the intermediate +product is calculated to infinite precision and is not subject to +the FCSR Flush to Zero bit. This may be undesirable in some +circumstances. @item -nocpp @opindex nocpp Tell the MIPS assembler to not run its preprocessor over user assembler files (with a @samp{.s} suffix) when assembling them. -@item -mfix7000 -@opindex mfix7000 -Pass an option to gas which will cause nops to be inserted if -the read of the destination register of an mfhi or mflo instruction -occurs in the following two instructions. - -@item -no-crt0 -@opindex no-crt0 -Do not include the default crt0. +@item -mfix-sb1 +@itemx -mno-fix-sb1 +@opindex mfix-sb1 +Work around certain SB-1 CPU core errata. +(This flag currently works around the SB-1 revision 2 +``F1'' and ``F2'' floating point errata.) @item -mflush-func=@var{func} @itemx -mno-flush-func @@ -7808,7 +8101,7 @@ call any such function. If called, the function must take the same arguments as the common @code{_flush_func()}, that is, the address of the memory range for which the cache is being flushed, the size of the memory range, and the number 3 (to flush both caches). The default -depends on the target gcc was configured for, but commonly is either +depends on the target GCC was configured for, but commonly is either @samp{_flush_func} or @samp{__cpu_flush}. @item -mbranch-likely @@ -7835,28 +8128,79 @@ These @samp{-m} options are defined for the i386 and x86-64 family of computers: @table @gcctabopt -@item -mcpu=@var{cpu-type} -@opindex mcpu +@item -mtune=@var{cpu-type} +@opindex mtune Tune to @var{cpu-type} everything applicable about the generated code, except for the ABI and the set of available instructions. The choices for -@var{cpu-type} are @samp{i386}, @samp{i486}, @samp{i586}, @samp{i686}, -@samp{pentium}, @samp{pentium-mmx}, @samp{pentiumpro}, @samp{pentium2}, -@samp{pentium3}, @samp{pentium4}, @samp{k6}, @samp{k6-2}, @samp{k6-3}, -@samp{athlon}, @samp{athlon-tbird}, @samp{athlon-4}, @samp{athlon-xp}, -@samp{athlon-mp}, @samp{winchip-c6}, @samp{winchip2} and @samp{c3}. +@var{cpu-type} are: +@table @emph +@item i386 +Original Intel's i386 CPU. +@item i486 +Intel's i486 CPU. (No scheduling is implemented for this chip.) +@item i586, pentium +Intel Pentium CPU with no MMX support. +@item pentium-mmx +Intel PentiumMMX CPU based on Pentium core with MMX instruction set support. +@item i686, pentiumpro +Intel PentiumPro CPU. +@item pentium2 +Intel Pentium2 CPU based on PentiumPro core with MMX instruction set support. +@item pentium3, pentium3m +Intel Pentium3 CPU based on PentiumPro core with MMX and SSE instruction set +support. +@item pentium-m +Low power version of Intel Pentium3 CPU with MMX, SSE and SSE2 instruction set +support. Used by Centrino notebooks. +@item pentium4, pentium4m +Intel Pentium4 CPU with MMX, SSE and SSE2 instruction set support. +@item prescott +Improved version of Intel Pentium4 CPU with MMX, SSE, SSE2 and SSE3 instruction +set support. +@item nocona +Improved version of Intel Pentium4 CPU with 64-bit extensions, MMX, SSE, +SSE2 and SSE3 instruction set support. +@item k6 +AMD K6 CPU with MMX instruction set support. +@item k6-2, k6-3 +Improved versions of AMD K6 CPU with MMX and 3dNOW! instruction set support. +@item athlon, athlon-tbird +AMD Athlon CPU with MMX, 3dNOW!, enhanced 3dNOW! and SSE prefetch instructions +support. +@item athlon-4, athlon-xp, athlon-mp +Improved AMD Athlon CPU with MMX, 3dNOW!, enhanced 3dNOW! and full SSE +instruction set support. +@item k8, opteron, athlon64, athlon-fx +AMD K8 core based CPUs with x86-64 instruction set support. (This supersets +MMX, SSE, SSE2, 3dNOW!, enhanced 3dNOW! and 64-bit instruction set extensions.) +@item winchip-c6 +IDT Winchip C6 CPU, dealt in same way as i486 with additional MMX instruction +set support. +@item winchip2 +IDT Winchip2 CPU, dealt in same way as i486 with additional MMX and 3dNOW! +instruction set support. +@item c3 +Via C3 CPU with MMX and 3dNOW! instruction set support. (No scheduling is +implemented for this chip.) +@item c3-2 +Via C3-2 CPU with MMX and SSE instruction set support. (No scheduling is +implemented for this chip.) +@end table While picking a specific @var{cpu-type} will schedule things appropriately for that particular chip, the compiler will not generate any code that does not run on the i386 without the @option{-march=@var{cpu-type}} option -being used. @samp{i586} is equivalent to @samp{pentium} and @samp{i686} -is equivalent to @samp{pentiumpro}. @samp{k6} and @samp{athlon} are the -AMD chips as opposed to the Intel ones. +being used. @item -march=@var{cpu-type} @opindex march Generate instructions for the machine type @var{cpu-type}. The choices -for @var{cpu-type} are the same as for @option{-mcpu}. Moreover, -specifying @option{-march=@var{cpu-type}} implies @option{-mcpu=@var{cpu-type}}. +for @var{cpu-type} are the same as for @option{-mtune}. Moreover, +specifying @option{-march=@var{cpu-type}} implies @option{-mtune=@var{cpu-type}}. + +@item -mcpu=@var{cpu-type} +@opindex mcpu +A deprecated synonym for @option{-mtune}. @item -m386 @itemx -m486 @@ -7866,13 +8210,13 @@ specifying @option{-march=@var{cpu-type}} implies @option{-mcpu=@var{cpu-type}}. @opindex m486 @opindex mpentium @opindex mpentiumpro -These options are synonyms for @option{-mcpu=i386}, @option{-mcpu=i486}, -@option{-mcpu=pentium}, and @option{-mcpu=pentiumpro} respectively. +These options are synonyms for @option{-mtune=i386}, @option{-mtune=i486}, +@option{-mtune=pentium}, and @option{-mtune=pentiumpro} respectively. These synonyms are deprecated. @item -mfpmath=@var{unit} @opindex march -generate floating point arithmetics for selected unit @var{unit}. the choices +Generate floating point arithmetics for selected unit @var{unit}. The choices for @var{unit} are: @table @samp @@ -7898,24 +8242,17 @@ For i387 you need to use @option{-march=@var{cpu-type}}, @option{-msse} or @option{-msse2} switches to enable SSE extensions and make this option effective. For x86-64 compiler, these extensions are enabled by default. -The resulting code should be considerably faster in majority of cases and avoid +The resulting code should be considerably faster in the majority of cases and avoid the numerical instability problems of 387 code, but may break some existing code that expects temporaries to be 80bit. -This is the default choice for x86-64 compiler. - -@item pni -Use all SSE extensions enabled by @option{-msse2} as well as the new -SSE extensions in Prescott New Intrunctions. @option{-mpni} also -enables 2 builtin functions, @code{__builtin_ia32_monitor} and -@code{__builtin_ia32_mwait}, for new intrunctions @code{monitor} and -@code{mwait}. +This is the default choice for the x86-64 compiler. @item sse,387 Attempt to utilize both instruction sets at once. This effectively double the amount of available registers and on chips with separate execution units for 387 and SSE the execution resources too. Use this option with care, as it is -still experimental, because gcc register allocator does not model separate +still experimental, because the GCC register allocator does not model separate functional units well resulting in instable performance. @end table @@ -7985,31 +8322,31 @@ and will not be binary compatible with structures in code compiled without that switch. @item -m96bit-long-double -@item -m128bit-long-double +@itemx -m128bit-long-double @opindex m96bit-long-double @opindex m128bit-long-double -These switches control the size of @code{long double} type. The i386 -application binary interface specifies the size to be 96 bits, +These switches control the size of @code{long double} type. The i386 +application binary interface specifies the size to be 96 bits, so @option{-m96bit-long-double} is the default in 32 bit mode. Modern architectures (Pentium and newer) would prefer @code{long double} -to be aligned to an 8 or 16 byte boundary. In arrays or structures -conforming to the ABI, this would not be possible. So specifying a +to be aligned to an 8 or 16 byte boundary. In arrays or structures +conforming to the ABI, this would not be possible. So specifying a @option{-m128bit-long-double} will align @code{long double} to a 16 byte boundary by padding the @code{long double} with an additional -32 bit zero. +32 bit zero. In the x86-64 compiler, @option{-m128bit-long-double} is the default choice as its ABI specifies that @code{long double} is to be aligned on 16 byte boundary. - + Notice that neither of these options enable any extra precision over the x87 -standard of 80 bits for a @code{long double}. +standard of 80 bits for a @code{long double}. @strong{Warning:} if you override the default value for your target ABI, the -structures and arrays containing @code{long double} will change their size as -well as function calling convention for function taking @code{long double} -will be modified. Hence they will not be binary compatible with arrays or -structures in code compiled without that switch. +structures and arrays containing @code{long double} variables will change +their size as well as function calling convention for function taking +@code{long double} will be modified. Hence they will not be binary +compatible with arrays or structures in code compiled without that switch. @item -msvr3-shlib @@ -8092,8 +8429,8 @@ preferred alignment to @option{-mpreferred-stack-boundary=2}. @itemx -mno-sse @item -msse2 @itemx -mno-sse2 -@item -mpni -@itemx -mno-pni +@item -msse3 +@itemx -mno-sse3 @item -m3dnow @itemx -mno-3dnow @opindex mmmx @@ -8103,7 +8440,8 @@ preferred alignment to @option{-mpreferred-stack-boundary=2}. @opindex m3dnow @opindex mno-3dnow These switches enable or disable the use of built-in functions that allow -direct access to the MMX, SSE and 3Dnow extensions of the instruction set. +direct access to the MMX, SSE, SSE2, SSE3 and 3Dnow extensions of the +instruction set. @xref{X86 Built-in Functions}, for details of the functions enabled and disabled by these switches. @@ -8140,7 +8478,7 @@ on thread-safe exception handling must compile and link all code with the @opindex mno-align-stringops Do not align destination of inlined string operations. This switch reduces code size and improves performance in case the destination is already aligned, -but gcc don't know about it. +but GCC doesn't know about it. @item -minline-all-stringops @opindex minline-all-stringops @@ -8156,6 +8494,17 @@ avoids the instructions to save, set up and restore frame pointers and makes an extra register available in leaf functions. The option @option{-fomit-frame-pointer} removes the frame pointer for all functions which might make debugging harder. + +@item -mtls-direct-seg-refs +@itemx -mno-tls-direct-seg-refs +@opindex mtls-direct-seg-refs +Controls whether TLS variables may be accessed with offsets from the +TLS segment register (@code{%gs} for 32-bit, @code{%fs} for 64-bit), +or whether the thread base pointer must be added. Whether or not this +is legal depends on the operating system, and whether it maps the +segment to cover the entire TLS area. + +For systems that use GNU libc, the default is on. @end table These @samp{-m} switches are supported in addition to the above @@ -8334,7 +8683,7 @@ building a shared library. It is the default when GCC is configured, explicitly or implicitly, with the GNU linker. This option does not have any affect on which ld is called, it only changes what parameters are passed to that ld. The ld that is called is determined by the -@option{--with-ld} configure option, gcc's program search path, and +@option{--with-ld} configure option, GCC's program search path, and finally by the user's @env{PATH}. The linker used by GCC can be printed using @samp{which `gcc -print-prog-name=ld`}. @@ -8346,7 +8695,7 @@ links. It is the default when GCC is configured, explicitly or implicitly, with the HP linker. This option does not have any affect on which ld is called, it only changes what parameters are passed to that ld. The ld that is called is determined by the @option{--with-ld} -configure option, gcc's program search path, and finally by the user's +configure option, GCC's program search path, and finally by the user's @env{PATH}. The linker used by GCC can be printed using @samp{which `gcc -print-prog-name=ld`}. @@ -8746,6 +9095,19 @@ heap instead of in the program's data segment. When generating code for shared libraries, @option{-fpic} implies @option{-msmall-data} and @option{-fPIC} implies @option{-mlarge-data}. +@item -msmall-text +@itemx -mlarge-text +@opindex msmall-text +@opindex mlarge-text +When @option{-msmall-text} is used, the compiler assumes that the +code of the entire program (or shared library) fits in 4MB, and is +thus reachable with a branch instruction. When @option{-msmall-data} +is used, the compiler can assume that all local symbols share the +same @code{$gp} value, and thus reduce the number of instructions +required for a function call from 4 to 1. + +The default is @option{-mlarge-text}. + @item -mcpu=@var{cpu_type} @opindex mcpu Set the instruction set and instruction scheduling parameters for @@ -8760,7 +9122,7 @@ Supported values for @var{cpu_type} are @table @samp @item ev4 -@item ev45 +@itemx ev45 @itemx 21064 Schedules as an EV4 and has no instruction set extensions. @@ -8782,7 +9144,7 @@ Schedules as an EV5 and supports the BWX and MAX extensions. Schedules as an EV6 and supports the BWX, FIX, and MAX extensions. @item ev67 -@item 21264a +@itemx 21264a Schedules as an EV6 and supports the BWX, CIX, FIX, and MAX extensions. @end table @@ -8838,7 +9200,7 @@ These @samp{-m} options are defined for the H8/300 implementations: @opindex mrelax Shorten some address references at link time, when possible; uses the linker option @option{-relax}. @xref{H8/300,, @code{ld} and the H8/300, -ld.info, Using ld}, for a fuller description. +ld, Using ld}, for a fuller description. @item -mh @opindex mh @@ -8884,6 +9246,9 @@ Generate code for the SH1. @opindex m2 Generate code for the SH2. +@item -m2e +Generate code for the SH2e. + @item -m3 @opindex m3 Generate code for the SH3. @@ -9029,7 +9394,7 @@ parameters for machine type @var{cpu_type}. Supported values for TMS320C40. @item -mbig-memory -@item -mbig +@itemx -mbig @itemx -msmall-memory @itemx -msmall @opindex mbig-memory @@ -9238,15 +9603,21 @@ the compiler. This setting is the default. @item -mno-app-regs @opindex mno-app-regs This option will cause r2 and r5 to be treated as fixed registers. - + +@item -mv850e1 +@opindex mv850e1 +Specify that the target processor is the V850E1. The preprocessor +constants @samp{__v850e1__} and @samp{__v850e__} will be defined if +this option is used. + @item -mv850e @opindex mv850e Specify that the target processor is the V850E. The preprocessor constant @samp{__v850e__} will be defined if this option is used. -If neither @option{-mv850} nor @option{-mv850e} are defined -then a default target processor will be chosen and the relevant -@samp{__v850*__} preprocessor constant will be defined. +If neither @option{-mv850} nor @option{-mv850e} nor @option{-mv850e1} +are defined then a default target processor will be chosen and the +relevant @samp{__v850*__} preprocessor constant will be defined. The preprocessor constants @samp{__v850} and @samp{__v851__} are always defined, regardless of which processor variant is the target. @@ -9254,7 +9625,7 @@ defined, regardless of which processor variant is the target. @item -mdisable-callt @opindex mdisable-callt This option will suppress generation of the CALLT instruction for the -v850e flavors of the v850 architecture. The default is +v850e and v850e1 flavors of the v850 architecture. The default is @option{-mno-disable-callt} which allows the CALLT instruction to be used. @end table @@ -9582,7 +9953,7 @@ Generate code for a big endian target. This is the default for HP-UX@. @item -mlittle-endian @opindex mlittle-endian Generate code for a little endian target. This is the default for AIX5 -and Linux. +and GNU/Linux. @item -mgnu-as @itemx -mno-gnu-as @@ -9674,6 +10045,14 @@ A fixed register is one that the register allocator can not use. This is useful when compiling kernel code. A register range is specified as two registers separated by a dash. Multiple register ranges can be specified separated by a comma. + +@item -mearly-stop-bits +@itemx -mno-early-stop-bits +@opindex mearly-stop-bits +@opindex mno-early-stop-bits +Allow stop bits to be placed earlier than immediately preceding the +instruction that triggered the stop bit. This can improve instruction +scheduling, but does not always do so. @end table @node D30V Options @@ -9743,8 +10122,9 @@ generates IEEE floating-point instructions. This is the default. @opindex mno-backchain Generate (or do not generate) code which maintains an explicit backchain within the stack frame that points to the caller's frame. -This is currently needed to allow debugging. The default is to -generate the backchain. +This may be needed to allow debugging using tools that do not understand +DWARF-2 call frame information. The default is not to generate the +backchain. @item -msmall-exec @itemx -mno-small-exec @@ -9761,12 +10141,25 @@ which does not have this limitation. @opindex m64 @opindex m31 When @option{-m31} is specified, generate code compliant to the -Linux for S/390 ABI@. When @option{-m64} is specified, generate -code compliant to the Linux for zSeries ABI@. This allows GCC in +GNU/Linux for S/390 ABI@. When @option{-m64} is specified, generate +code compliant to the GNU/Linux for zSeries ABI@. This allows GCC in particular to generate 64-bit instructions. For the @samp{s390} targets, the default is @option{-m31}, while the @samp{s390x} targets default to @option{-m64}. +@item -mzarch +@itemx -mesa +@opindex mzarch +@opindex mesa +When @option{-mzarch} is specified, generate code using the +instructions available on z/Architecture. +When @option{-mesa} is specified, generate code using the +instructions available on ESA/390. Note that @option{-mesa} is +not possible with @option{-m64}. +When generating code compliant to the GNU/Linux for S/390 ABI, +the default is @option{-mesa}. When generating code compliant +to the GNU/Linux for zSeries ABI, the default is @option{-mzarch}. + @item -mmvcle @itemx -mno-mvcle @opindex mmvcle @@ -9782,6 +10175,29 @@ use a @code{mvc} loop instead. This is the default. Print (or do not print) additional debug information when compiling. The default is to not print debug information. +@item -march=@var{cpu-type} +@opindex march +Generate code that will run on @var{cpu-type}, which is the name of a system +representing a certain processor type. Possible values for +@var{cpu-type} are @samp{g5}, @samp{g6}, @samp{z900}, and @samp{z990}. +When generating code using the instructions available on z/Architecture, +the default is @option{-march=z900}. Otherwise, the default is +@option{-march=g5}. + +@item -mtune=@var{cpu-type} +@opindex mtune +Tune to @var{cpu-type} everything applicable about the generated code, +except for the ABI and the set of available instructions. +The list of @var{cpu-type} values is the same as for @option{-march}. +The default is the value used for @option{-march}. + +@item -mfused-madd +@itemx -mno-fused-madd +@opindex mfused-madd +@opindex mno-fused-madd +Generate code that uses (does not use) the floating point multiply and +accumulate instructions. These instructions are generated by default if +hardware floating point is used. @end table @node CRIS Options @@ -9825,6 +10241,13 @@ program should be set to @var{n} bytes. The options @option{-metrax4} and @option{-metrax100} are synonyms for @option{-march=v3} and @option{-march=v8} respectively. +@item -mmul-bug-workaround +@itemx -mno-mul-bug-workaround +@opindex mmul-bug-workaround +@opindex mno-mul-bug-workaround +Work around a bug in the @code{muls} and @code{mulu} instructions for CPU +models where it applies. This option is active by default. + @item -mpdebug @opindex mpdebug Enable CRIS-specific verbose debug-related information in the assembly @@ -10071,7 +10494,7 @@ Use 32-bit @code{int}. Use 64-bit @code{float}. This is the default. @item -mfloat32 -@item -mno-float64 +@itemx -mno-float64 @opindex mfloat32 @opindex mno-float64 Use 32-bit @code{float}. @@ -10355,100 +10778,19 @@ Select the processor type for which to generate code. Possible values are @subsection Xtensa Options @cindex Xtensa Options -The Xtensa architecture is designed to support many different -configurations. The compiler's default options can be set to match a -particular Xtensa configuration by copying a configuration file into the -GCC sources when building GCC@. The options below may be used to -override the default options. +These options are supported for Xtensa targets: @table @gcctabopt -@item -mbig-endian -@itemx -mlittle-endian -@opindex mbig-endian -@opindex mlittle-endian -Specify big-endian or little-endian byte ordering for the target Xtensa -processor. - -@item -mdensity -@itemx -mno-density -@opindex mdensity -@opindex mno-density -Enable or disable use of the optional Xtensa code density instructions. - -@item -mmac16 -@itemx -mno-mac16 -@opindex mmac16 -@opindex mno-mac16 -Enable or disable use of the Xtensa MAC16 option. When enabled, GCC -will generate MAC16 instructions from standard C code, with the -limitation that it will use neither the MR register file nor any -instruction that operates on the MR registers. When this option is -disabled, GCC will translate 16-bit multiply/accumulate operations to a -combination of core instructions and library calls, depending on whether -any other multiplier options are enabled. - -@item -mmul16 -@itemx -mno-mul16 -@opindex mmul16 -@opindex mno-mul16 -Enable or disable use of the 16-bit integer multiplier option. When -enabled, the compiler will generate 16-bit multiply instructions for -multiplications of 16 bits or smaller in standard C code. When this -option is disabled, the compiler will either use 32-bit multiply or -MAC16 instructions if they are available or generate library calls to -perform the multiply operations using shifts and adds. - -@item -mmul32 -@itemx -mno-mul32 -@opindex mmul32 -@opindex mno-mul32 -Enable or disable use of the 32-bit integer multiplier option. When -enabled, the compiler will generate 32-bit multiply instructions for -multiplications of 32 bits or smaller in standard C code. When this -option is disabled, the compiler will generate library calls to perform -the multiply operations using either shifts and adds or 16-bit multiply -instructions if they are available. - -@item -mnsa -@itemx -mno-nsa -@opindex mnsa -@opindex mno-nsa -Enable or disable use of the optional normalization shift amount -(@code{NSA}) instructions to implement the built-in @code{ffs} function. - -@item -mminmax -@itemx -mno-minmax -@opindex mminmax -@opindex mno-minmax -Enable or disable use of the optional minimum and maximum value -instructions. - -@item -msext -@itemx -mno-sext -@opindex msext -@opindex mno-sext -Enable or disable use of the optional sign extend (@code{SEXT}) -instruction. - -@item -mbooleans -@itemx -mno-booleans -@opindex mbooleans -@opindex mno-booleans -Enable or disable support for the boolean register file used by Xtensa -coprocessors. This is not typically useful by itself but may be -required for other options that make use of the boolean registers (e.g., -the floating-point option). - -@item -mhard-float -@itemx -msoft-float -@opindex mhard-float -@opindex msoft-float -Enable or disable use of the floating-point option. When enabled, GCC -generates floating-point instructions for 32-bit @code{float} -operations. When this option is disabled, GCC generates library calls -to emulate 32-bit floating-point operations using integer instructions. -Regardless of this option, 64-bit @code{double} operations are always -emulated with calls to library functions. +@item -mconst16 +@itemx -mno-const16 +@opindex mconst16 +@opindex mno-const16 +Enable or disable use of @code{CONST16} instructions for loading +constant values. The @code{CONST16} instruction is currently not a +standard option from Tensilica. When enabled, @code{CONST16} +instructions are always used in place of the standard @code{L32R} +instructions. The use of @code{CONST16} is enabled by default only if +the @code{L32R} instruction is not available. @item -mfused-madd @itemx -mno-fused-madd @@ -10467,15 +10809,6 @@ add/subtract instructions also ensures that the program output is not sensitive to the compiler's ability to combine multiply and add/subtract operations. -@item -mserialize-volatile -@itemx -mno-serialize-volatile -@opindex mserialize-volatile -@opindex mno-serialize-volatile -When this option is enabled, GCC inserts @code{MEMW} instructions before -@code{volatile} memory references to guarantee sequential consistency. -The default is @option{-mserialize-volatile}. Use -@option{-mno-serialize-volatile} to omit the @code{MEMW} instructions. - @item -mtext-section-literals @itemx -mno-text-section-literals @opindex mtext-section-literals @@ -10552,6 +10885,14 @@ this option defaults to true and false respectively. This option generates traps for signed overflow on addition, subtraction, multiplication operations. +@item -fwrapv +@opindex fwrapv +This option instructs the compiler to assume that signed arithmetic +overflow of addition, subtraction and multiplication wraps around +using twos-complement representation. This flag enables some optimizations +and disables other. This option is enabled by default for the Java +front-end, as required by the Java language specification. + @item -fexceptions @opindex fexceptions Enable exception handling. Generates extra code needed to propagate @@ -10674,17 +11015,6 @@ program will work on other systems which always work this way. @opindex fno-ident Ignore the @samp{#ident} directive. -@item -fno-gnu-linker -@opindex fno-gnu-linker -Do not output global initializations (such as C++ constructors and -destructors) in the form used by the GNU linker (on systems where the GNU -linker is the standard method of handling them). Use this option when -you want to use a non-GNU linker, which also requires using the -@command{collect2} program to make sure the system linker includes -constructors and destructors. (@command{collect2} is included in the GCC -distribution.) For systems which @emph{must} use @command{collect2}, the -compiler driver @command{gcc} is configured to do this automatically. - @item -finhibit-size-directive @opindex finhibit-size-directive Don't output a @code{.size} assembler directive, or anything else that @@ -10704,20 +11034,6 @@ debugging the compiler itself). extra information to be omitted and is useful when comparing two assembler files. -@item -fvolatile -@opindex fvolatile -Consider all memory references through pointers to be volatile. - -@item -fvolatile-global -@opindex fvolatile-global -Consider all memory references to extern and global data items to -be volatile. GCC does not consider static data items to be volatile -because of this switch. - -@item -fvolatile-static -@opindex fvolatile-static -Consider all memory references to static data to be volatile. - @item -fpic @opindex fpic @cindex global offset table @@ -10730,7 +11046,7 @@ loader is not part of GCC; it is part of the operating system). If the GOT size for the linked executable exceeds a machine-specific maximum size, you get an error message from the linker indicating that @option{-fpic} does not work; in that case, recompile with @option{-fPIC} -instead. (These maximums are 16k on the m88k, 8k on the SPARC, and 32k +instead. (These maximums are 8k on the SPARC and 32k on the m68k and RS/6000. The 386 has no such limit.) Position-independent code requires special support, and therefore works @@ -10742,12 +11058,21 @@ position-independent. @opindex fPIC If supported for the target machine, emit position-independent code, suitable for dynamic linking and avoiding any limit on the size of the -global offset table. This option makes a difference on the m68k, m88k, +global offset table. This option makes a difference on the m68k and the SPARC. Position-independent code requires special support, and therefore works only on certain machines. +@item -fpie +@itemx -fPIE +@opindex fpie +@opindex fPIE +These options are similar to @option{-fpic} and @option{-fPIC}, but +generated position independent code can be only linked into executables. +Usually these options are used when @option{-pie} GCC option will be +used during linking. + @item -ffixed-@var{reg} @opindex ffixed Treat the register named @var{reg} as a fixed register; generated code @@ -10811,26 +11136,18 @@ function and its call site. (On some platforms, function, so the call site information may not be available to the profiling functions otherwise.) -@example +@smallexample void __cyg_profile_func_enter (void *this_fn, void *call_site); void __cyg_profile_func_exit (void *this_fn, void *call_site); -@end example +@end smallexample The first argument is the address of the start of the current function, which may be looked up exactly in the symbol table. -This instrumentation is also done for functions expanded inline in other -functions. The profiling calls will indicate where, conceptually, the -inline function is entered and exited. This means that addressable -versions of such functions must be available. If all your uses of a -function are expanded inline, this may mean an additional expansion of -code size. If you use @samp{extern inline} in your C code, an -addressable version of such functions must be provided. (This is -normally the case anyways, but if you get lucky and the optimizer always -expands the functions inline, you might have gotten away without -providing static copies.) +This currently disables function inlining. This restriction is +expected to be removed in future releases. A function may be given the attribute @code{no_instrument_function}, in which case this instrumentation will not be done. This can be used, for @@ -10992,7 +11309,7 @@ If GCC cannot find the subprogram using the specified prefix, it tries looking in the usual places for the subprogram. The default value of @env{GCC_EXEC_PREFIX} is -@file{@var{prefix}/lib/gcc-lib/} where @var{prefix} is the value +@file{@var{prefix}/lib/gcc/} where @var{prefix} is the value of @code{prefix} when you ran the @file{configure} script. Other prefixes specified with @option{-B} take precedence over this prefix. @@ -11002,7 +11319,7 @@ used for linking. In addition, the prefix is used in an unusual way in finding the directories to search for header files. For each of the standard -directories whose name normally begins with @samp{/usr/local/lib/gcc-lib} +directories whose name normally begins with @samp{/usr/local/lib/gcc} (more precisely, with the value of @env{GCC_INCLUDE_DIR}), GCC tries replacing that beginning with the specified prefix to produce an alternate directory name. Thus, with @option{-Bfoo/}, GCC will search @@ -11058,6 +11375,111 @@ preprocessor. @c man end +@node Precompiled Headers +@section Using Precompiled Headers +@cindex precompiled headers +@cindex speed of compilation + +Often large projects have many header files that are included in every +source file. The time the compiler takes to process these header files +over and over again can account for nearly all of the time required to +build the project. To make builds faster, GCC allows users to +`precompile' a header file; then, if builds can use the precompiled +header file they will be much faster. + +@strong{Caution:} There are a few known situations where GCC will +crash when trying to use a precompiled header. If you have trouble +with a precompiled header, you should remove the precompiled header +and compile without it. In addition, please use GCC's on-line +defect-tracking system to report any problems you encounter with +precompiled headers. @xref{Bugs}. + +To create a precompiled header file, simply compile it as you would any +other file, if necessary using the @option{-x} option to make the driver +treat it as a C or C++ header file. You will probably want to use a +tool like @command{make} to keep the precompiled header up-to-date when +the headers it contains change. + +A precompiled header file will be searched for when @code{#include} is +seen in the compilation. As it searches for the included file +(@pxref{Search Path,,Search Path,cpp,The C Preprocessor}) the +compiler looks for a precompiled header in each directory just before it +looks for the include file in that directory. The name searched for is +the name specified in the @code{#include} with @samp{.gch} appended. If +the precompiled header file can't be used, it is ignored. + +For instance, if you have @code{#include "all.h"}, and you have +@file{all.h.gch} in the same directory as @file{all.h}, then the +precompiled header file will be used if possible, and the original +header will be used otherwise. + +Alternatively, you might decide to put the precompiled header file in a +directory and use @option{-I} to ensure that directory is searched +before (or instead of) the directory containing the original header. +Then, if you want to check that the precompiled header file is always +used, you can put a file of the same name as the original header in this +directory containing an @code{#error} command. + +This also works with @option{-include}. So yet another way to use +precompiled headers, good for projects not designed with precompiled +header files in mind, is to simply take most of the header files used by +a project, include them from another header file, precompile that header +file, and @option{-include} the precompiled header. If the header files +have guards against multiple inclusion, they will be skipped because +they've already been included (in the precompiled header). + +If you need to precompile the same header file for different +languages, targets, or compiler options, you can instead make a +@emph{directory} named like @file{all.h.gch}, and put each precompiled +header in the directory. (It doesn't matter what you call the files +in the directory, every precompiled header in the directory will be +considered.) The first precompiled header encountered in the +directory that is valid for this compilation will be used; they're +searched in no particular order. + +There are many other possibilities, limited only by your imagination, +good sense, and the constraints of your build system. + +A precompiled header file can be used only when these conditions apply: + +@itemize +@item +Only one precompiled header can be used in a particular compilation. +@item +A precompiled header can't be used once the first C token is seen. You +can have preprocessor directives before a precompiled header; you can +even include a precompiled header from inside another header, so long as +there are no C tokens before the @code{#include}. +@item +The precompiled header file must be produced for the same language as +the current compilation. You can't use a C precompiled header for a C++ +compilation. +@item +The precompiled header file must be produced by the same compiler +version and configuration as the current compilation is using. +The easiest way to guarantee this is to use the same compiler binary +for creating and using precompiled headers. +@item +Any macros defined before the precompiled header (including with +@option{-D}) must either be defined in the same way as when the +precompiled header was generated, or must not affect the precompiled +header, which usually means that the they don't appear in the +precompiled header at all. +@item +Certain command-line options must be defined in the same way as when the +precompiled header was generated. At present, it's not clear which +options are safe to change and which are not; the safest choice is to +use exactly the same options when generating and using the precompiled +header. +@end itemize + +For all of these but the last, the compiler will automatically ignore +the precompiled header if the conditions aren't met. For the last item, +some option changes will cause the precompiled header to be rejected, +but not all incompatible option combinations have yet been found. If +you find a new incompatible combination, please consider filing a bug +report, see @ref{Bugs}. + @node Running Protoize @section Running Protoize @@ -11198,10 +11620,10 @@ appropriate options and the option @option{-aux-info}. Then run the existing @samp{.X} file because it is newer than the source file. For example: -@example +@smallexample gcc -Dfoo=bar file1.c -aux-info file1.X protoize *.c -@end example +@end smallexample @noindent You need to include the special files along with the rest in the |
