[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2. GCC Command Options

When you invoke GCC, it normally does preprocessing, compilation, assembly and linking. The "overall options" allow you to stop this process at an intermediate stage. For example, the `-c' option says not to run the linker. Then the output consists of object files output by the assembler.

Other options are passed on to one stage of processing. Some options control the preprocessor and others the compiler itself. Yet other options control the assembler and linker; most of these are not documented here, since you rarely need to use any of them.

Most of the command line options that you can use with GCC are useful for C programs; when an option is only useful with another language (usually C++), the explanation says so explicitly. If the description for a particular option does not mention a source language, you can use that option with all supported languages.

See section Compiling C++ Programs, for a summary of special options for compiling C++ programs.

The gcc program accepts options and file names as operands. Many options have multiletter names; therefore multiple single-letter options may not be grouped: `-dr' is very different from `-d -r'.

You can mix options and other arguments. For the most part, the order you use doesn't matter. Order does matter when you use several options of the same kind; for example, if you specify `-L' more than once, the directories are searched in the order specified.

Many options have long names starting with `-f' or with `-W'---for example, `-fforce-mem', `-fstrength-reduce', `-Wformat' and so on. Most of these have both positive and negative forms; the negative form of `-ffoo' would be `-fno-foo'. This manual documents only one of these two forms, whichever one is not the default.

2.1 Option Summary  Brief list of all options, without explanations.
2.2 Options Controlling the Kind of Output  Controlling the kind of output: an executable, object files, assembler files, or preprocessed source.
2.3 Compiling C++ Programs  Compiling C++ programs.
2.4 Options Controlling C Dialect  Controlling the variant of C language compiled.
2.5 Options Controlling C++ Dialect  Variations on C++.
2.6 Options to Request or Suppress Warnings  How picky should the compiler be?
2.7 Options for Debugging Your Program or GCC  Symbol tables, measurements, and debugging dumps.
2.8 Options That Control Optimization  How much optimization?
2.9 Options Controlling the Preprocessor  Controlling header files and macro definitions. Also, getting dependency information for Make.
2.10 Passing Options to the Assembler  Passing options to the assembler.
2.11 Options for Linking  Specifying libraries and so on.
2.12 Options for Directory Search  Where to find header files and libraries. Where to find the compiler executable files.
2.13 Specifying subprocesses and the switches to pass to them  How to pass switches to sub-processes.
2.14 Specifying Target Machine and Compiler Version  Running a cross-compiler, or an old version of GCC.
2.15 Different CPUs and Configurations  Specifying minor hardware or convention variations, such as r3000 vs r4000.
2.16 Options for Code Generation Conventions  Specifying conventions for function calls, data layout and register usage.
2.17 Environment Variables Affecting GCC  Env vars that affect GCC.
2.18 Running Protoize  Automatically adding or removing function prototypes.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.1 Option Summary

Here is a summary of all the options, grouped by type. Explanations are in the following sections.

Overall Options
See section Options Controlling the Kind of Output.
 
-c  -S  -E  -o file  -pipe  -pass-exit-codes  -v  --help  -x language

C Language Options
See section Options Controlling C Dialect.
 
-ansi -fstd  -fallow-single-precision  -fcond-mismatch  -fno-asm
-fno-builtin  -ffreestanding  -fhosted  -fsigned-bitfields
-funsigned-bitfields  -fsigned-char  -funsigned-char
-fwritable-strings  -traditional  -traditional-cpp  -trigraphs

C++ Language Options
See section Options Controlling C++ Dialect.
 
-fno-access-control -fcheck-new -fconserve-space
-fdollars-in-identifiers -fno-elide-constructors -fexternal-templates
-ffor-scope -fno-for-scope -fno-gnu-keywords -fguiding-decls -fhonor-std
-fhuge-objects -fno-implicit-templates -finit-priority
-fno-implement-inlines -fname-mangling-version-n
-fno-default-inline -fno-operator-names -fno-optional-diags -fpermissive
-frepo -fstrict-prototype -fsquangle -ftemplate-depth-n
-fuse-cxa-atexit -fvtable-thunks -nostdinc++ -Wctor-dtor-privacy
-Wno-deprecated -Weffc++ -Wno-non-template-friend -Wnon-virtual-dtor
-Wold-style-cast -Woverloaded-virtual -Wno-pmf-conversions -Wreorder
-Wsign-promo -Wsynth

Warning Options
See section Options to Request or Suppress Warnings.
 
-fsyntax-only  -pedantic  -pedantic-errors
-w  -W  -Wall  -Waggregate-return 
-Wcast-align  -Wcast-qual  -Wchar-subscripts  -Wcomment
-Wconversion  -Werror  -Wformat
-Wid-clash-len  -Wimplicit -Wimplicit-int 
-Wimplicit-function-declaration  -Wimport
-Werror-implicit-function-declaration  -Wfloat-equal -Winline
-Wlarger-than-len  -Wlong-long
-Wmain  -Wmissing-declarations  -Wmissing-noreturn
-Wparentheses  -Wparentheses-else  -Wpointer-arith  -Wredundant-decls
-Wreturn-type  -Wlongjmp-clobbers  -Wshadow  -Wsign-compare
-Wstrict-prototypes  -Wswitch  -Wtraditional  
-Wmultichar  -Wno-import  -Wpacked  -Wpadded
-Wparentheses -Wpointer-arith  -Wredundant-decls
-Wreturn-type -Wshadow  -Wsign-compare -Wswitch
-Wtrigraphs -Wundef  -Wuninitialized  -Wunknown-pragmas -Wunreachable-code 
-Wunused -Wunused-function -Wunused-label -Wunused-parameter
-Wunused-variable -Wunused-value -Wwrite-strings

C-only Warning Options
 
-Wbad-function-cast -Wmissing-prototypes -Wnested-externs
-Wstrict-prototypes -Wtraditional

Debugging Options
See section Options for Debugging Your Program or GCC.
 
-dletters  -fdump-unnumbered -fdump-translation-unit-file
-fpretend-float -fprofile-arcs  -ftest-coverage
-g  -glevel  -gcoff  -gdwarf  -gdwarf-1  -gdwarf-1+  -gdwarf-2
-ggdb  -gstabs  -gstabs+  -gxcoff  -gxcoff+
-p  -pg  -print-file-name=library  -print-libgcc-file-name
-print-prog-name=program  -print-search-dirs  -save-temps  -time

Optimization Options
See section Options that Control Optimization.
 
-falign-functions=n  -falign-labels=n  -falign-loops=n 
-falign-jumps=n  -fbranch-probabilities  
-fcaller-saves  -fcse-follow-jumps  -fcse-skip-blocks
-flive-range
-fdelayed-branch  -fdelete-null-pointer-checks -fexpensive-optimizations
-ffast-math  -ffloat-store  -fforce-addr  -fforce-mem -fno-math-errno
-fdata-sections  -ffunction-sections  -fgcse 
-finline-functions  -finline-limit=n  -fkeep-inline-functions
-fmove-all-movables  -fno-default-inline  -fno-defer-pop
-fno-function-cse  -fno-inline  -fno-peephole
-fomit-frame-pointer  -foptimize-register-moves -foptimize-sibling-calls
-fregmove -frerun-cse-after-loop  -frerun-loop-opt  -freduce-all-givs
-fschedule-insns  -fschedule-insns2  -fssa -fstrength-reduce
-fstrict-aliasing  -fthread-jumps  -funroll-all-loops
-funroll-loops
-O  -O0  -O1  -O2  -O3 -Os

Preprocessor Options
See section Options Controlling the Preprocessor.
 
-Aquestion(answer)  -C  -dD  -dM  -dN
-Dmacro[=defn]  -E  -H
-idirafter dir
-include file  -imacros file
-iprefix file  -iwithprefix dir
-iwithprefixbefore dir  -isystem dir -isystem-c++ dir
-M  -MD  -MM  -MMD  -MG  -nostdinc  -P  -trigraphs
-undef  -Umacro  -Wp,option

Assembler Option
See section Passing Options to the Assembler.
 
-Wa,option

Linker Options
See section Options for Linking.
 
object-file-name  -llibrary
-nostartfiles  -nodefaultlibs  -nostdlib
-s  -static  -shared  -symbolic
-Wl,option  -Xlinker option
-u symbol

Directory Options
See section Options for Directory Search.
 
-Bprefix  -Idir  -I-  -Ldir  -specs=file

Options specific to MIPS Processors and/or MIPS SDE
See section Different CPUs and Configurations
 
-mcpu=cpu type
-mips1  -mips2  -mips3  -mips4  -mips5  
-mips32  -mips32r2 -mips64 -mips64r2
-mips16  -mips16e  -msmartmips  -mips3D 
-mcode-xonly  -mno-data-in-code 
-muse-all-regs -mbranch-likely
-mcheck-zero-division  -mno-check-zero-division
-mdiv-checks  -mno-div-checks
-mconst-mult  -mno-const-mult
-mfp32  -mfp64  -mgp32  -mgp64
-msplit-addresses  -mrnames  -mgpopt
-mstats
-mmemcpy
-msoft-float  -mhard-float  -msingle-float 
-mslow-mul  -mno-mul  -mmad  -mno-mad
-membedded-data  -mno-embedded-data  -mgpconst  -mno-gpconst
-muninit-const-in-rodata  -mno-uninit-const-in-rodata
-mlong-calls  -mcommon-prolog  -mentry
-EL  -EB
-G num
-nocpp

-mabi=32  -mabi=n32  -mabi=64  -mabi=eabi  -mabi=meabi
-mabicalls  -mno-abicalls
-mint64  -mlong64  -mgas  -mmips-as
-mhalf-pic  -mno-half-pic  -membedded-pic  -mno-embedded-pic
-mmips-tfile  -mno-mips-tfile

Code Generation Options
See section Options for Code Generation Conventions.
 
-fcall-saved-reg  -fcall-used-reg
-fexceptions  -funwind-tables  -ffixed-reg  -finhibit-size-directive
-fcheck-memory-usage  -fprefix-function-name
-fno-common  -fcommon  -fno-ident  -fno-gnu-linker
-fpcc-struct-return  -fpic  -fPIC
-freg-struct-return  -fshared-data  -fshort-enums
-fshort-double  -fvolatile  -fvolatile-global -fvolatile-static
-funaligned-pointers  -funaligned-struct-hack
-foptimize-comparisons
-fverbose-asm  -fpack-struct  -fstack-check
-fstack-limit-register=reg  -fstack-limit-symbol=sym
-fargument-alias  -fargument-noalias
-fargument-noalias-global
-fleading-underscore

2.2 Options Controlling the Kind of Output  Controlling the kind of output: an executable, object files, assembler files, or preprocessed source.
2.4 Options Controlling C Dialect  Controlling the variant of C language compiled.
2.5 Options Controlling C++ Dialect  Variations on C++.
2.6 Options to Request or Suppress Warnings  How picky should the compiler be?
2.7 Options for Debugging Your Program or GCC  Symbol tables, measurements, and debugging dumps.
2.8 Options That Control Optimization  How much optimization?
2.9 Options Controlling the Preprocessor  Controlling header files and macro definitions. Also, getting dependency information for Make.
2.10 Passing Options to the Assembler  Passing options to the assembler.
2.11 Options for Linking  Specifying libraries and so on.
2.12 Options for Directory Search  Where to find header files and libraries. Where to find the compiler executable files.
2.13 Specifying subprocesses and the switches to pass to them  How to pass switches to sub-processes.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.2 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.

For any given input file, the file name suffix determines what kind of compilation is done:

file.c
C source code which must be preprocessed.

file.i
C source code which should not be preprocessed.

file.ii
C++ source code which should not be preprocessed.

file.m
Objective-C source code. Note that you must link with the library `libobjc.a' to make an Objective-C program work.

file.h
C header file (not to be compiled or linked).

file.cc
file.cxx
file.cpp
file.C
C++ source code which must be preprocessed. Note that in `.cxx', the last two letters must both be literally `x'. Likewise, `.C' refers to a literal capital C.

file.s
Assembler code.

file.S
file.sx
Assembler code which must be preprocessed. The file.sx form is used in Windows, where filenames are case-insensitive.

other
An object file to be fed straight into linking. Any file name with no recognized suffix is treated this way.

You can specify the input language explicitly with the `-x' option:

-x language
Specify explicitly the 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 `-x' option. Possible values for language are:
 
c  objective-c  c++
c-header  cpp-output  c++-cpp-output
assembler  assembler-with-cpp

-x none
Turn off any specification of a language, so that subsequent files are handled according to their file name suffixes (as they are if `-x' has not been used at all).

-pass-exit-codes
Normally the gcc program will exit with the code of 1 if any phase of the compiler returns a non-success return code. If you specify `-pass-exit-codes', the gcc program will instead return with numerically highest error produced by any phase that returned an error indication.

If you only want some of the stages of compilation, you can use `-x' (or filename suffixes) to tell gcc where to start, and one of the options `-c', `-S', or `-E' to say where gcc is to stop. Note that some combinations (for example, `-x cpp-output -E' instruct gcc to do nothing at all.

-c
Compile or assemble the source files, but do not link. The linking stage simply is not done. The ultimate output is in the form of an object file for each source file.

By default, the object file name for a source file is made by replacing the suffix `.c', `.i', `.s', etc., with `.o'.

Unrecognized input files, not requiring compilation or assembly, are ignored.

-S
Stop after the stage of compilation proper; do not assemble. The output is in the form of an assembler code file for each non-assembler input file specified.

By default, the assembler file name for a source file is made by replacing the suffix `.c', `.i', etc., with `.s'.

Input files that don't require compilation are ignored.

-E
Stop after the preprocessing stage; do not run the compiler proper. The output is in the form of preprocessed source code, which is sent to the standard output.

Input files which don't require preprocessing are ignored.

-o file
Place output in file 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 `-o' when compiling more than one input file, unless you are producing an executable file as output.

If `-o' is not specified, the default is to put an executable file in `a.out', the object file for `source.suffix' in `source.o', its assembler file in `source.s', and all preprocessed C source on standard output.

-v
Print (on standard error output) the commands executed to run the stages of compilation. Also print the version number of the compiler driver program and of the preprocessor and the compiler proper.

-pipe
Use pipes rather than temporary files for communication between the various stages of compilation. This fails to work on some systems where the assembler is unable to read from a pipe; but the GNU assembler has no trouble.

--print-multi-directory
Prints the name of the library "multilib" subdirectory that will be used for this set of options.

--print-search-dirs
Prints the list of directories searched for programs (eg `cc1', `cpp', etc) and libraries.

--print-file-name=file
--print-prog-name=program
Prints the location of the library or program file given the previous options. For example `--print-file-name=cc1' will tell you which program is being used for the main compiler pass, and `--print-file-name=libc.a' will tell you where the C library is coming from.

--help
Print (on the standard output) a description of the command line options understood by gcc. If the -v option is also specified then --help will also be passed on to the various processes invoked by gcc, so that they can display the command line options they accept. If the -W option is also specified then command line options which have no documentation associated with them will also be displayed.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.3 Compiling C++ Programs

C++ source files conventionally use one of the suffixes `.C', `.cc', `.cpp', `.c++', `.cp', or `.cxx'; preprocessed C++ files use the suffix `.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 gcc).

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. 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, the script g++ is also installed with the name c++.

When you compile C++ programs, you may specify many of the same command-line options that you use for compiling programs in any language; or command-line options meaningful for C and related languages; or options that are meaningful only for C++ programs. See section Options Controlling C Dialect, for explanations of options for languages related to C. See section Options Controlling C++ Dialect, for explanations of options that are meaningful only for C++ programs.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.4 Options Controlling C Dialect

The following options control the dialect of C (or languages derived from C, such as C++ and Objective C) that the compiler accepts:

-ansi
In C mode, support all ANSI standard C programs. In C++ mode, remove GNU extensions that conflict with ISO C++.

This turns off certain features of GCC that are incompatible with ANSI C (when compiling C code), or of standard C++ (when compiling C++ code), such as the asm and typeof keywords, and predefined macros such as unix and vax that identify the type of system you are using. It also enables the undesirable and rarely used ANSI trigraph feature. For the C compiler, it disables recognition of C++ style `//' comments as well as the inline keyword.

The alternate keywords __asm__, __extension__, __inline__ and __typeof__ continue to work despite `-ansi'. You would not want to use them in an ANSI C program, of course, but it is useful to put them in header files that might be included in compilations done with `-ansi'. Alternate predefined macros such as __unix__ and __vax__ are also available, with or without `-ansi'.

The `-ansi' option does not cause non-ANSI programs to be rejected gratuitously. For that, `-pedantic' is required in addition to `-ansi'. See section 2.6 Options to Request or Suppress Warnings.

The macro __STRICT_ANSI__ is predefined when the `-ansi' option is used. Some header files may notice this macro and refrain from declaring certain functions or defining certain macros that the ANSI standard doesn't call for; this is to avoid interfering with any programs that might use these names for other things.

The functions alloca, abort, exit, and _exit are not builtin functions when `-ansi' is used.

-fstd=
Determine the language standard. A value for this option must be provided; possible values are

Even when this option is not specified, you can still use some of the features of newer standards in so far as they do not conflict with previous C standards. For example, you may use __restrict__ even when -fstd=c9x is not specified.

-fno-asm
Do not recognize asm, inline or typeof as a keyword, so that code can use these words as identifiers. You can use the keywords __asm__, __inline__ and __typeof__ instead. `-ansi' implies `-fno-asm'.

In C++, this switch only affects the typeof keyword, since asm and inline are standard keywords. You may want to use the `-fno-gnu-keywords' flag instead, which has the same effect.

-fno-builtin
Don't recognize builtin functions that do not begin with `__builtin_' as prefix. Currently, the functions affected include abort, abs, alloca, cos, cosf, cosl, exit, _exit, fabs, fabsf, fabsl, ffs, labs, memcmp, memcpy, memset, sin, sinf, sinl, sqrt, sqrtf, sqrtl, strcmp, strcpy, and strlen.

GCC normally generates special code to handle certain builtin functions more efficiently; for instance, calls to alloca may become single instructions that adjust the stack directly, and calls to memcpy may become inline copy loops. The resulting code is often both smaller and faster, but since the function calls no longer appear as such, you cannot set a breakpoint on those calls, nor can you change the behavior of the functions by linking with a different library.

The `-ansi' option prevents alloca, ffs and _exit from being builtin functions, since these functions do not have an ANSI standard meaning.

-fhosted

Assert that compilation takes place in a hosted environment. This implies `-fbuiltin'. A hosted environment is one in which the entire standard library is available, and in which main has a return type of int. Examples are nearly everything except a kernel. This is equivalent to `-fno-freestanding'.

-ffreestanding

Assert that compilation takes place in a freestanding environment. This implies `-fno-builtin'. A freestanding environment is one in which the standard library may not exist, and program startup may not necessarily be at main. The most obvious example is an OS kernel. This is equivalent to `-fno-hosted'.

-trigraphs
Support ANSI C trigraphs. You don't want to know about this brain-damage. The `-ansi' option implies `-trigraphs'.

-traditional
Attempt to support some aspects of traditional C compilers. Specifically:

You may wish to use `-fno-builtin' as well as `-traditional' if your program uses names that are normally GNU C builtin functions for other purposes of its own.

You cannot use `-traditional' if you include any header files that rely on ANSI C features. Some vendors are starting to ship systems with ANSI C header files and you cannot use `-traditional' on such systems to compile files that include any system headers.

The `-traditional' option also enables `-traditional-cpp', which is described next.

-traditional-cpp
Attempt to support some aspects of traditional C preprocessors. Specifically:

-fcond-mismatch
Allow conditional expressions with mismatched types in the second and third arguments. The value of such an expression is void.

-funsigned-char
Let the type char be unsigned, like unsigned char.

Each kind of machine has a default for what char should be. It is either like unsigned char by default or like signed char by default.

Ideally, a portable program should always use signed char or unsigned char when it depends on the signedness of an object. But many programs have been written to use plain char and expect it to be signed, or expect it to be unsigned, depending on the machines they were written for. This option, and its inverse, let you make such a program work with the opposite default.

The type char is always a distinct type from each of signed char or unsigned char, even though its behavior is always just like one of those two.

-fsigned-char
Let the type char be signed, like signed char.

Note that this is equivalent to `-fno-unsigned-char', which is the negative form of `-funsigned-char'. Likewise, the option `-fno-signed-char' is equivalent to `-funsigned-char'.

You may wish to use `-fno-builtin' as well as `-traditional' if your program uses names that are normally GNU C builtin functions for other purposes of its own.

You cannot use `-traditional' if you include any header files that rely on ANSI C features. Some vendors are starting to ship systems with ANSI C header files and you cannot use `-traditional' on such systems to compile files that include any system headers.

-fsigned-bitfields
-funsigned-bitfields
-fno-signed-bitfields
-fno-unsigned-bitfields
These options control whether a bitfield is signed or unsigned, when the declaration does not use either signed or unsigned. By default, such a bitfield is signed, because this is consistent: the basic integer types such as int are signed types.

However, when `-traditional' is used, bitfields are all unsigned no matter what.

-fwritable-strings
Store string constants in the writable data segment and don't uniquize them. This is for compatibility with old programs which assume they can write into string constants. The option `-traditional' also has this effect.

Writing into string constants is a very bad idea; "constants" should be constant.

-fallow-single-precision
Do not promote single precision math operations to double precision, even when compiling with `-traditional'.

Traditional K&R C promotes all floating point operations to double precision, regardless of the sizes of the operands. On the architecture for which you are compiling, single precision may be faster than double precision. If you must use `-traditional', but want to use single precision operations when the operands are single precision, use this option. This option has no effect when compiling with ANSI or GNU C conventions (the default).

-fshort-wchar
Override the underlying type for `wchar_t' to be `short unsigned int' instead of the default for the target. This option is useful for building programs to run under WINE.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.5 Options Controlling C++ Dialect

This section describes the command-line options that are only meaningful 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 firstClass.C like this:

 
g++ -g -frepo -O -c firstClass.C

In this example, only `-frepo' is an option meant only for C++ programs; you can use the other options with any language supported by GCC.

Here is a list of options that are only for compiling C++ programs:

-fno-access-control
Turn off all access checking. This switch is mainly useful for working around bugs in the access control code.

-fcheck-new
Check that the pointer returned by operator new is non-null before attempting to modify the storage allocated. The current Working Paper requires that operator new never return a null pointer, so this check is normally unnecessary.

An alternative to using this option is to specify that your operator new does not throw any exceptions; if you declare it `throw()', g++ will check the return value. See also `new (nothrow)'.

-fconserve-space
Put uninitialized or runtime-initialized global variables into the common segment, as C does. This saves space in the executable at the cost of not diagnosing duplicate definitions. If you compile with this flag and your program mysteriously crashes after main() has completed, you may have an object that is being destroyed twice because two definitions were merged.

This option is no longer useful on most targets, now that support has been added for putting variables into BSS without making them common.

-fdollars-in-identifiers
Accept `$' in identifiers. You can also explicitly prohibit use of `$' with the option `-fno-dollars-in-identifiers'. (GNU C allows `$' by default on most target systems, but there are a few exceptions.) Traditional C allowed the character `$' to form part of identifiers. However, ANSI C and C++ forbid `$' in identifiers.

-fembedded-cxx
In compliance with the Embedded C++ specification, make the use of templates, exception handling, multiple inheritance, or RTTI illegal. Attempts to use namespaces are also not allowed. This makes the use of these keywords result in warnings by default: template, typename, catch, throw, try, using, namespace, dynamic_cast, static_cast, reinterpret_cast, const_cast, and typeid. To make the warnings for these things be given as errors, add the -pedantic-errors flag.

-fno-elide-constructors
The C++ standard allows an implementation to omit creating a temporary which is only used to initialize another object of the same type. Specifying this option disables that optimization, and forces g++ to call the copy constructor in all cases.

-fno-enforce-eh-specs
Don't check for violation of exception specifications at runtime. This option violates the C++ standard, but may be useful for reducing code size in production builds, much like defining `NDEBUG'. The compiler will still optimize based on the exception specifications.

-fexternal-templates
Cause template instantiations to obey `#pragma interface' and
`implementation'; template instances are emitted or not according to the location of the template definition.
See section 4.6 Where's the Template?, for more information.

This option is deprecated.

-falt-external-templates
Similar to -fexternal-templates, but template instances are emitted or not according to the place where they are first instantiated. See section 4.6 Where's the Template?, for more information.

This option is deprecated.

-ffor-scope
-fno-for-scope
If -ffor-scope is specified, the scope of variables declared in a for-init-statement is limited to the `for' loop itself, as specified by the C++ standard. If -fno-for-scope is specified, the scope of variables declared in a for-init-statement extends to the end of the enclosing scope, as was the case in old versions of gcc, and other (traditional) implementations of C++.

The default if neither flag is given to follow the standard, but to allow and give a warning for old-style code that would otherwise be invalid, or have different behavior.

-fno-gnu-keywords
Do not recognize typeof as a keyword, so that code can use this word as an identifier. You can use the keyword __typeof__ instead. `-ansi' implies `-fno-gnu-keywords'.

-fguiding-decls
Treat a function declaration with the same type as a potential function template instantiation as though it declares that instantiation, not a normal function. If a definition is given for the function later in the translation unit (or another translation unit if the target supports weak symbols), that definition will be used; otherwise the template will be instantiated. This behavior reflects the C++ language prior to September 1996, when guiding declarations were removed.

This option implies `-fname-mangling-version-0', and will not work with other name mangling versions. Like all options that change the ABI, all C++ code, including libgcc.a must be built with the same setting of this option.

-fno-implicit-templates
Never emit code for templates which are instantiated implicitly (i.e. by use); only emit code for explicit instantiations. See section 4.6 Where's the Template?, for more information.

-fhonor-std
Treat the namespace std as a namespace, instead of ignoring it. For compatibility with earlier versions of g++, the compiler will, by default, ignore namespace-declarations, using-declarations, using-directives, and namespace-names, if they involve std.

-fhuge-objects
Support virtual function calls for objects that exceed the size representable by a `short int'. Users should not use this flag by default; if you need to use it, the compiler will tell you so.

This flag is not useful when compiling with -fvtable-thunks.

Like all options that change the ABI, all C++ code, including libgcc must be built with the same setting of this option.

-fmessage-length=n
Try to format error messages so that they fit on lines of about n characters. The default is 72 characters. If n is zero, then no line-wrapping will be done; each error message will appear on a single line.

-fno-implicit-templates
Never emit code for non-inline templates which are instantiated implicitly (i.e. by use); only emit code for explicit instantiations. See section 4.6 Where's the Template?, for more information.

-fno-implicit-inline-templates
Don't emit code for implicit instantiations of inline templates, either. The default is to handle inlines differently so that compiles with and without optimization will need the same set of explicit instantiations.

-finit-priority
Support `__attribute__ ((init_priority (n)))' for controlling the order of initialization of file-scope objects. On ELF targets, this requires GNU ld 2.10 or later.

-fno-implement-inlines
To save space, do not emit out-of-line copies of inline functions controlled by `#pragma implementation'. This will cause linker errors if these functions are not inlined everywhere they are called.

-fms-extensions
Disable pedwarns about constructs used in MFC, such as implicit int and getting a pointer to member function via non-standard syntax.

-fname-mangling-version-n
Control the way in which names are mangled. Version 0 is compatible with versions of g++ before 2.8. Version 1 is the default. Version 1 will allow correct mangling of function templates. For example, version 0 mangling does not mangle foo<int, double> and foo<int, char> given this declaration:

 
template <class T, class U> void foo(T t);

Like all options that change the ABI, all C++ code, including libgcc must be built with the same setting of this option.

-fno-operator-names
Do not treat the operator name keywords and, bitand, bitor, compl, not, or and xor as synonyms as keywords.

-fno-optional-diags
Disable diagnostics that the standard says a compiler does not need to issue. Currently, the only such diagnostic issued by g++ is the one for a name having multiple meanings within a class.

-fpermissive
Downgrade messages about nonconformant code from errors to warnings. By default, g++ effectively sets `-pedantic-errors' without `-pedantic'; this option reverses that. This behavior and this option are superseded by `-pedantic', which works as it does for GNU C.

-frepo
Enable automatic template instantiation. This option also implies
`-fno-implicit-templates'. See section 4.6 Where's the Template?, for more information.

-fno-rtti
Disable generation of information about every class with virtual functions for use by the C++ runtime type identification features (`dynamic_cast' and `typeid'). If you don't use those parts of the language, you can save some space by using this flag. Note that exception handling uses the same information, but it will generate it as needed.

-fstrict-prototype
Within an `extern "C"' linkage specification, treat a function declaration with no arguments, such as `int foo ();', as declaring the function to take no arguments. Normally, such a declaration means that the function foo can take any combination of arguments, as in C. `-pedantic' implies `-fstrict-prototype' unless overridden with `-fno-strict-prototype'.

Specifying this option will also suppress implicit declarations of functions.

This flag no longer affects declarations with C++ linkage.

-fsquangle
-fno-squangle
`-fsquangle' will enable a compressed form of name mangling for identifiers. In particular, it helps to shorten very long names by recognizing types and class names which occur more than once, replacing them with special short ID codes. This option also requires any C++ libraries being used to be compiled with this option as well. The compiler has this disabled (the equivalent of `-fno-squangle') by default.

Like all options that change the ABI, all C++ code, including libgcc.a must be built with the same setting of this option.

-ftemplate-depth-n
Set the maximum instantiation depth for template classes to n. A limit on the template instantiation depth is needed to detect endless recursions during template class instantiation. ANSI/ISO C++ conforming programs must not rely on a maximum depth greater than 17.

-fuse-cxa-atexit
Register destructors for objects with static storage duration with the __cxa_atexit function rather than the atexit function. This option is required for fully standards-compliant handling of static destructors, but will only work if your C library supports __cxa_atexit.

-fvtable-thunks
Use `thunks' to implement the virtual function dispatch table (`vtable'). The traditional (cfront-style) approach to implementing vtables was to store a pointer to the function and two offsets for adjusting the `this' pointer at the call site. Newer implementations store a single pointer to a `thunk' function which does any necessary adjustment and then calls the target function.

This option also enables a heuristic for controlling emission of vtables; if a class has any non-inline virtual functions, the vtable will be emitted in the translation unit containing the first one of those.

In the MIPS SDE compiler `thunks' are used by default. Like all options that change the ABI, all C++ code, including libgcc.a must be built with the same setting of this option.

-nostdinc++
Do not search for header files in the standard directories specific to C++, but do still search the other standard directories. (This option is used when building the C++ library.)

In addition, these optimization, warning, and code generation options have meanings only for C++ programs:

-fno-default-inline
Do not assume `inline' for functions defined inside a class scope. See section Options That Control Optimization. Note that these functions will have linkage like inline functions; they just won't be inlined by default.

-Wctor-dtor-privacy (C++ only)
Warn when a class seems unusable, because all the constructors or destructors in a class are private and the class has no friends or public static member functions.

-Wnon-virtual-dtor (C++ only)
Warn when a class declares a non-virtual destructor that should probably be virtual, because it looks like the class will be used polymorphically.

-Wreorder (C++ only)
Warn when the order of member initializers given in the code does not match the order in which they must be executed. For instance:

 
struct A {
  int i;
  int j;
  A(): j (0), i (1) { }
};

Here the compiler will warn that the member initializers for `i' and `j' will be rearranged to match the declaration order of the members.

The following `-W...' options are not affected by `-Wall'.

-Weffc++ (C++ only)
Warn about violations of various style guidelines from Scott Meyers' Effective C++ books. If you use this option, you should be aware that the standard library headers do not obey all of these guidelines; you can use `grep -v' to filter out those warnings.

-Wno-deprecated (C++ only)
Do not warn about usage of deprecated features. See section 3.42 Deprecated Features.

-Wno-non-template-friend (C++ only)
Disable warnings when non-templatized friend functions are declared within a template. With the advent of explicit template specification support in g++, if the name of the friend is an unqualified-id (ie, `friend foo(int)'), the C++ language specification demands that the friend declare or define an ordinary, nontemplate function. (Section 14.5.3). Before g++ implemented explicit specification, unqualified-ids could be interpreted as a particular specialization of a templatized function. Because this non-conforming behavior is no longer the default behavior for g++, `-Wnon-template-friend' allows the compiler to check existing code for potential trouble spots, and is on by default. This new compiler behavior can also be turned off with the flag `-fguiding-decls', which activates the older, non-specification compiler code, or with `-Wno-non-template-friend' which keeps the conformant compiler code but disables the helpful warning.

-Wold-style-cast (C++ only)
Warn if an old-style (C-style) cast is used within a C++ program. The new-style casts (`static_cast', `reinterpret_cast', and `const_cast') are less vulnerable to unintended effects.

-Woverloaded-virtual (C++ only)
Warn when a derived class function declaration may be an error in defining a virtual function. In a derived class, the definitions of virtual functions must match the type signature of a virtual function declared in the base class. With this option, the compiler warns when you define a function with the same name as a virtual function, but with a type signature that does not match any declarations from the base class.

-Wno-pmf-conversions (C++ only)
Disable the diagnostic for converting a bound pointer to member function to a plain pointer.

-Wsign-promo (C++ only)
Warn when overload resolution chooses a promotion from unsigned or enumeral 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.

-Wsynth (C++ only)
Warn when g++'s synthesis behavior does not match that of cfront. For instance:

 
struct A {
  operator int ();
  A& operator = (int);
};

main ()
{
  A a,b;
  a = b;
}

In this example, g++ will synthesize a default `A& operator = (const A&);', while cfront will use the user-defined `operator ='.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.6 Options to Request or Suppress Warnings

Warnings are diagnostic messages that report constructions which are not inherently erroneous but which are risky or suggest there may have been an error.

You can request many specific warnings with options beginning `-W', for example `-Wimplicit' to request warnings on implicit declarations. Each of these specific warning options also has a negative form beginning `-Wno-' to turn off warnings; for example, `-Wno-implicit'. This manual lists only one of the two forms, whichever is not the default.

These options control the amount and kinds of warnings produced by GCC:

-fsyntax-only
Check the code for syntax errors, but don't do anything beyond that.

-pedantic
Issue all the warnings demanded by strict ANSI C and ISO C++; reject all programs that use forbidden extensions.

Valid ANSI C and ISO C++ programs should compile properly with or without this option (though a rare few will require `-ansi'). However, without this option, certain GNU extensions and traditional C and C++ features are supported as well. With this option, they are rejected.

`-pedantic' does not cause warning messages for use of the alternate keywords whose names begin and end with `__'. Pedantic warnings are also disabled in the expression that follows __extension__. However, only system header files should use these escape routes; application programs should avoid them. See section 3.36 Alternate Keywords.

This option is not intended to be useful; it exists only to satisfy pedants who would otherwise claim that GCC fails to support the ANSI standard.

Some users try to use `-pedantic' to check programs for strict ANSI C conformance. They soon find that it does not do quite what they want: it finds some non-ANSI practices, but not all--only those for which ANSI C requires a diagnostic.

A feature to report any failure to conform to ANSI C might be useful in some instances, but would require considerable additional work and would be quite different from `-pedantic'. We don't have plans to support such a feature in the near future.

-pedantic-errors
Like `-pedantic', except that errors are produced rather than warnings.

-w
Inhibit all warning messages.

-Wno-import
Inhibit warning messages about the use of `#import'.

-Wchar-subscripts
Warn if an array subscript has type char. This is a common cause of error, as programmers often forget that this type is signed on some machines.

-Wcomment
Warn whenever a comment-start sequence `/*' appears in a `/*' comment, or whenever a Backslash-Newline appears in a `//' comment.

-Wformat
Check calls to printf and scanf, etc., to make sure that the arguments supplied have types appropriate to the format string specified.

-Wimplicit-int
Warn when a declaration does not specify a type.

-Wimplicit-function-declaration
-Werror-implicit-function-declaration
Give a warning (or error) whenever a function is used before being declared.

-Wimplicit
Same as `-Wimplicit-int' and `-Wimplicit-function-'
`declaration'.

-Wmain
Warn if the type of `main' is suspicious. `main' should be a function with external linkage, returning int, taking either zero arguments, two, or three arguments of appropriate types.

-Wmultichar
Warn if a multicharacter constant (`'FOOF'') is used. Usually they indicate a typo in the user's code, as they have implementation-defined values, and should not be used in portable code.

-Wparentheses
Warn if parentheses are omitted in certain contexts, such as when there is an assignment in a context where a truth value is expected, or when operators are nested whose precedence people often get confused about.

This option includes `-Wparentheses-else' below.

-Wparentheses-else
Also warn about constructions where there may be confusion to which if statement an else branch belongs. Here is an example of such a case:

 
{
  if (a)
    if (b)
      foo ();
  else
    bar ();
}

In C, every else branch belongs to the innermost possible if statement, which in this example is if (b). This is often not what the programmer expected, as illustrated in the above example by indentation the programmer chose. When there is the potential for this confusion, GNU C will issue a warning when this flag is specified. To eliminate the warning, add explicit braces around the innermost if statement so there is no way the else could belong to the enclosing if. The resulting code would look like this:

 
{
  if (a)
    {
      if (b)
        foo ();
      else
        bar ();
    }
}

-Wreturn-type
Warn whenever a function is defined with a return-type that defaults to int. Also warn about any return statement with no return-value in a function whose return-type is not void.

-Wswitch
Warn whenever a switch statement has an index of enumeral type and lacks a case for one or more of the named codes of that enumeration. (The presence of a default label prevents this warning.) case labels outside the enumeration range also provoke warnings when this option is used.

-Wtrigraphs
Warn if any trigraphs are encountered (assuming they are enabled).

-Wunused-function
Warn whenever a static function is declared but not defined or a non\-inline static function is unused.

-Wunused-label
Warn whenever a label is declared but not used.

To suppress this warning use the `unused' attribute (see section 3.29 Specifying Attributes of Variables).

-Wunused-parameter
Warn whenever a function parameter is unused aside from its declaration.

To suppress this warning use the `unused' attribute (see section 3.29 Specifying Attributes of Variables).

-Wunused-variable
Warn whenever a local variable or non-constant static variable is unused aside from its declaration

To suppress this warning use the `unused' attribute (see section 3.29 Specifying Attributes of Variables).

-Wunused-value
Warn whenever a statement computes a result that is explicitly not used.

To suppress this warning cast the expression to `void'.

-Wunused
All all the above `-Wunused' options combined.

In order to get a warning about an unused function parameter, you must either specify `-W -Wunused' or separatly specify `-Wunused-parameter'.

-Wuninitialized
Warn if an automatic variable is used without first being initialized or if a variable may be clobbered by a setjmp call.

These warnings are possible only in optimizing compilation, because they require data flow information that is computed only when optimizing. If you don't specify `-O', you simply won't get these warnings.

These warnings occur only for variables that are candidates for register allocation. Therefore, they do not occur for a variable that is declared volatile, or whose address is taken, or whose size is other than 1, 2, 4 or 8 bytes. Also, they do not occur for structures, unions or arrays, even when they are in registers.

Note that there may be no warning about a variable that is used only to compute a value that itself is never used, because such computations may be deleted by data flow analysis before the warnings are printed.

These warnings are made optional because GCC is not smart enough to see all the reasons why the code might be correct despite appearing to have an error. Here is one example of how this can happen:

 
{
  int x;
  switch (y)
    {
    case 1: x = 1;
      break;
    case 2: x = 4;
      break;
    case 3: x = 5;
    }
  foo (x);
}

If the value of y is always 1, 2 or 3, then x is always initialized, but GCC doesn't know this. Here is another common case:

 
{
  int save_y;
  if (change_y) save_y = y, y = new_y;
  ...
  if (change_y) y = save_y;
}

This has no bug because save_y is used only if it is set.

This option also includes `-Wlongjmp-clobbers' below.

-Wlongjmp-clobbers
Warn when a nonvolatile automatic variable might be changed by a call to longjmp. These warnings as well are possible only in optimizing compilation.

This option also warns when a nonvolatile automatic variable might be changed by a call to longjmp. These warnings as well are possible only in optimizing compilation.

The compiler sees only the calls to setjmp. It cannot know where longjmp will be called; in fact, a signal handler could call it at any point in the code. As a result, you may get a warning even when there is in fact no problem because longjmp cannot in fact be called at the place which would cause a problem.

Some spurious warnings can be avoided if you declare all the functions you use that never return as noreturn. See section 3.23 Declaring Attributes of Functions.

-Wreorder (C++ only)
Warn when the order of member initializers given in the code does not match the order in which they must be executed. For instance:

-Wunknown-pragmas
Warn when a #pragma directive is encountered which is not understood by GCC. If this command line option is used, warnings will even be issued for unknown pragmas in system header files. This is not the case if the warnings were only enabled by the `-Wall' command line option.

-Wall
All of the above `-W' options combined. This enables all the warnings about constructions that some users consider questionable, and that are easy to avoid (or modify to prevent the warning), even in conjunction with macros.

The following `-W...' options are not implied by `-Wall'. Some of them warn about constructions that users generally do not consider questionable, but which occasionally you might wish to check for; others warn about constructions that are necessary or hard to avoid in some cases, and there is no simple way to modify the code to suppress the warning.

-W
Print extra warning messages for these events:

-Wfloat-equal
Warn if floating point values are used in equality comparisons.

The idea behind this is that sometimes it is convenient (for the programmer) to consider floating-point values as approximations to infinitely precise real numbers. If you are doing this, then you need to compute (by analysing the code, or in some other way) the maximum or likely maximum error that the computation introduces, and allow for it when performing comparisons (and when producing output, but that's a different problem). In particular, instead of testing for equality, you would check to see whether the two values have ranges that overlap; and this is done with the relational operators, so equality comparisons are probably mistaken.

-Wtraditional (C only)
Warn about certain constructs that behave differently in traditional and ANSI C.

-Wundef
Warn if an undefined identifier is evaluated in an `#if' directive.

-Wshadow
Warn whenever a local variable shadows another local variable.

-Wid-clash-len
Warn whenever two distinct identifiers match in the first len characters. This may help you prepare a program that will compile with certain obsolete, brain-damaged compilers.

-Wlarger-than-len
Warn whenever an object of larger than len bytes is defined.

-Wpointer-arith
Warn about anything that depends on the "size of" a function type or of void. GNU C assigns these types a size of 1, for convenience in calculations with void * pointers and pointers to functions.

-Wbad-function-cast (C only)
Warn whenever a function call is cast to a non-matching type. For example, warn if int malloc() is cast to anything *.

-Wcast-qual
Warn whenever a pointer is cast so as to remove a type qualifier from the target type. For example, warn if a const char * is cast to an ordinary char *.

-Wcast-align
Warn whenever a pointer is cast such that the required alignment of the target is increased. For example, warn if a char * is cast to an int * on machines where integers can only be accessed at two- or four-byte boundaries.

-Wwrite-strings
Give string constants the type const char[length] so that copying the address of one into a non-const char * pointer will get a warning. These warnings will help you find at compile time code that can try to write into a string constant, but only if you have been very careful about using const in declarations and prototypes. Otherwise, it will just be a nuisance; this is why we did not make `-Wall' request these warnings.

-Wconversion
Warn if a prototype causes a type conversion that is different from what would happen to the same argument in the absence of a prototype. This includes conversions of fixed point to floating and vice versa, and conversions changing the width or signedness of a fixed point argument except when the same as the default promotion.

Also, warn if a negative integer constant expression is implicitly converted to an unsigned type. For example, warn about the assignment x = -1 if x is unsigned. But do not warn about explicit casts like (unsigned) -1.

-Wsign-compare
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 also enabled by `-W'; to get the other warnings of `-W' without this warning, use `-W -Wno-sign-compare'.

-Waggregate-return
Warn if any functions that return structures or unions are defined or called. (In languages where you can return an array, this also elicits a warning.)

-Wstrict-prototypes (C only)
Warn if a function is declared or defined without specifying the argument types. (An old-style function definition is permitted without a warning if preceded by a declaration which specifies the argument types.)

-Wmissing-prototypes (C only)
Warn if a global function is defined without a previous prototype declaration. This warning is issued even if the definition itself provides a prototype. The aim is to detect global functions that fail to be declared in header files.

-Wmissing-declarations
Warn if a global function is defined without a previous declaration. Do so even if the definition itself provides a prototype. Use this option to detect global functions that are not declared in header files.

-Wmissing-noreturn
Warn about functions which might be candidates for attribute noreturn. Note these are only possible candidates, not absolute ones. Care should be taken to manually verify functions actually do not ever return before adding the noreturn attribute, otherwise subtle code generation bugs could be introduced.

-Wpacked
Warn if a structure is given the packed attribute, but the packed attribute has no effect on the layout or size of the structure. Such structures may be mis-aligned for little benefit. For instance, in this code, the variable f.x in struct bar will be misaligned even though struct bar does not itself have the packed attribute:

 
struct foo {
  int x;
  char a, b, c, d;
} __attribute__((packed));
struct bar {
  char z;
  struct foo f;
};

-Wpadded
Warn if padding is included in a structure, either to align an element of the structure or to align the whole structure. Sometimes when this happens it is possible to rearrange the fields of the structure to reduce the padding and so make the structure smaller.

-Wredundant-decls
Warn if anything is declared more than once in the same scope, even in cases where multiple declaration is valid and changes nothing.

-Wnested-externs (C only)
Warn if an extern declaration is encountered within a function.

-Wunreachable-code
Warn if the compiler detects that code will never be executed.

This option is intended to warn when the compiler detects that at least a whole line of source code will never be executed, because some condition is never satisfied or because it is after a procedure that never returns.

It is possible for this option to produce a warning even though there are circumstances under which part of the affected line can be executed, so care should be taken when removing apparently-unreachable code.

For instance, when a function is inlined, a warning may mean that the line is unreachable in only one inlined copy of the function.

This option is not made part of `-Wall' because in a debugging version of a program there is often substantial code which checks correct functioning of the program and is, hopefully, unreachable because the program does work. Another common use of unreachable code is to provide behaviour which is selectable at compile-time.

-Winline
Warn if a function can not be inlined and it was declared as inline.

-Wlong-long
Warn if `long long' type is used. This is default. To inhibit the warning messages, use `-Wno-long-long'. Flags `-Wlong-long' and `-Wno-long-long' are taken into account only when `-pedantic' flag is used.

-Werror
Make all warnings into errors.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.7 Options for Debugging Your Program or GCC

GCC has various special options that are used for debugging either your program or GCC:

-g
Produce debugging information in the operating system's native format (stabs by default, ot DWARF if you ask for it). GDB can work with this debugging information.

On most systems that use stabs format, `-g' enables use of extra debugging information that only GDB can use; this extra information 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 `-gstabs+', `-gstabs', `-gdwarf-1+', or `-gdwarf-1' (see below).

Unlike most other C compilers, GCC allows you to use `-g' with `-O'. The shortcuts taken by optimized code may occasionally produce surprising results: some variables you declared may not exist at all; flow of control may briefly move where you did not expect it; some statements may not be executed because they compute constant results or their values were already at hand; some statements may execute in different places because they were moved out of loops.

Nevertheless it proves possible to debug optimized output. This makes it reasonable to use the optimizer for programs that might have bugs.

The following options are useful when GCC is generated with the capability for more than one debugging format.

-ggdb
Produce debugging information for use by GDB. This means to use the most expressive format available (DWARF 2, stabs, or the native format if neither of those are supported), including GDB extensions if at all possible.

-gstabs
Produce debugging information in stabs format (if that is supported), without GDB extensions. This is the format used by DBX on most BSD systems.

-gstabs+
Produce debugging information in stabs 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.

-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.

-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.

-gdwarf-2
Produce debugging information in DWARF version 2 format (if that is supported). This is the format used by DBX on IRIX 6.

-glevel
-ggdblevel
-gstabslevel
-gdwarflevel
-gdwarf-2level
Request debugging information and also use level to specify how much information. The default level is 2.

Level 1 produces minimal information, enough for making backtraces in parts of the program that you don't plan to debug. This includes descriptions of functions and external variables, but no information about local variables and no line numbers.

Level 3 includes extra information, such as all the macro definitions present in the program. Some debuggers support macro expansion when you use `-g3'.

-p
Generate extra code to write profile information suitable for the analysis program prof. You must use this option when compiling the source files you want data about, and you must also use it when linking.

-pg
Generate extra code to write profile information suitable for the analysis program gprof. You must use this option when compiling the source files you want data about, and you must also use it when linking.

-Q
Makes the compiler print out each function name as it is compiled, and print some statistics about each pass when it finishes.

-fprofile-arcs
Instrument arcs during compilation. For each function of your program, GCC creates a program flow graph, then finds a spanning tree for the graph. Only arcs that are not on the spanning tree have to be instrumented: the compiler adds code to count the number of times that these arcs are executed. When an arc is the only exit or only entrance to a block, the instrumentation code can be added to the block; otherwise, a new basic block must be created to hold the instrumentation code.

Since not every arc in the program must be instrumented, programs compiled with this option run faster than programs compiled with `-a', which adds instrumentation code to every basic block in the program. The tradeoff: since gcov does not have execution counts for all branches, it must start with the execution counts for the instrumented branches, and then iterate over the program flow graph until the entire graph has been solved. Hence, gcov runs a little more slowly than a program which uses information from `-a'.

`-fprofile-arcs' also makes it possible to estimate branch probabilities, and to calculate basic block execution counts. In general, basic block execution counts do not give enough information to estimate all branch probabilities. When the compiled program exits, it saves the arc execution counts to a file called `sourcename.da'. Use the compiler option `-fbranch-probabilities' (see section Options that Control Optimization) when recompiling, to optimize using estimated branch probabilities.

-ftest-coverage
Create data files for the gcov code-coverage utility (see section gcov: a GCC Test Coverage Program). The data file names begin with the name of your source file:

sourcename.bb
A mapping from basic blocks to line numbers, which gcov uses to associate basic block execution counts with line numbers.

sourcename.bbg
A list of all arcs in the program flow graph. This allows gcov to reconstruct the program flow graph, so that it can compute all basic block and arc execution counts from the information in the sourcename.da file (this last file is the output from `-fprofile-arcs').

-dletters
Says to make debugging dumps during compilation at times specified by letters. This is used for debugging the compiler. The file names for most of the dumps are made by appending a pass number and a word to the source file name (e.g. `foo.c.00.rtl' or `foo.c.01.jump'). Here are the possible letters for use in letters, and their meanings:

`A'
Annotate the assembler output with miscellaneous debugging information.
`b'
Dump after computing branch probabilities, to `file.10.bp'.
`B'
Dump after block reordering, to `file.20.bbro'.
`c'
Dump after instruction combination, to the file `file.12.combine'.
`d'
Dump after delayed branch scheduling, to `file.24.dbr'.
`D'
Dump all macro definitions, at the end of preprocessing, in addition to normal output.
`e'
Dump after SSA optimizations, to `file.05.ssa' and `file.06.ussa'.
`f'
Dump after flow analysis, to `file.11.flow'.
`F'
Dump after purging ADDRESSOF codes, to `file.04.addressof'.
`g'
Dump after global register allocation, to `file.16.greg'.
`G'
Dump after GCSE, to `file.07.gcse'.
`i'
Dump after sibling call optimizations, to `file.01.sibling'.
`j'
Dump after first jump optimization, to `file.02.jump'.
`J'
Dump after last jump optimization, to `file.22.jump2'.
`k'
Dump after conversion from registers to stack, to `file.25.stack'.
`l'
Dump after local register allocation, to `file.15.lreg'.
`L'
Dump after loop optimization, to `file.08.loop'.
`M'
Dump after performing the machine dependent reorganisation pass, to `file.23.mach'.
`n'
Dump after register renumbering, to `file.21.rnreg'.
`N'
Dump after the register move pass, to `file.13.regmove'.
`r'
Dump after RTL generation, to `file.00.rtl'.
`R'
Dump after the second instruction scheduling pass, to `file.19.sched2'.
`s'
Dump after CSE (including the jump optimization that sometimes follows CSE), to `file.03.cse'.
`S'
Dump after the first instruction scheduling pass, to `file.14.sched'.
`t'
Dump after the second CSE pass (including the jump optimization that sometimes follows CSE), to `file.09.cse2'.
`w'
Dump after the second flow pass, to `file.17.flow2'.
`z'
Dump after the peephole pass, to `file.18.peephole2'.
`a'
Produce all the dumps listed above.
`m'
Print statistics on memory usage, at the end of the run, to standard error.
`p'
Annotate the assembler output with a comment indicating which pattern and alternative was used. The length of each instruction is also printed.
`v'
For each of the other indicated dump files (except for `file.00.rtl'), dump a representation of the control flow graph suitible for viewing with VCG to `file.pass.vcg'.
`w'
Dump after the second flow pass to `file.14.flow2'.
`x'
Just generate RTL for a function instead of compiling it. Usually used with `r'.
`y'
Dump debugging information during parsing, to standard error.
`z'
Dump after the peephole2 pass to `file.15.peephole2'.

-fdump-unnumbered
When doing debugging dumps (see -d option above), suppress instruction numbers and line number note output. This makes it more feasible to use diff on debugging dumps for compiler invokations with different options, in particular with and without -g.

-fdump-translation-unit-file (C++ only)
Dump a representation of the tree structure for the entire translation unit to file.

-fpretend-float
When running a cross-compiler, pretend that the target machine uses the same floating point format as the host machine. This causes incorrect output of the actual floating constants, but the actual instruction sequence will probably be the same as GCC would make when running on the target machine.

-save-temps
Store the usual "temporary" intermediate files permanently; place them in the current directory and name them based on the source file. Thus, compiling `foo.c' with `-c -save-temps' would produce files `foo.i' and `foo.s', as well as `foo.o'.

-time
Report the CPU time taken by each subprocess in the compilation sequence. For C source files, this is the preprocessor, compiler proper, and assembler. The output looks like this:

 
# cpp 0.04 0.04
# cc1 0.12 0.01
# as 0.00 0.01

The first number on each line is the "user time," that is time spent executing the program itself. The second number is "system time," time spent executing operating system routines on behalf of the program. Both numbers are in seconds.

-print-file-name=library
Print the full absolute name of the library file library that would be used when linking--and don't do anything else. With this option, GCC does not compile or link anything; it just prints the file name.

-print-prog-name=program
Like `-print-file-name', but searches for a program such as `cpp'.

-print-libgcc-file-name
Same as `-print-file-name=libgcc.a'.

This is useful when you use `-nostdlib' or `-nodefaultlibs' but you do want to link with `libgcc.a'. You can do

 
gcc -nostdlib files... `gcc -print-libgcc-file-name`

-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.

This is useful when gcc prints the error message `installation problem, cannot exec cpp: No such file or directory'. To resolve this you either need to put `cpp' and the other compiler components where gcc expects to find them, or you can set the environment variable GCC_EXEC_PREFIX to the directory where you installed them. Don't forget the trailing '/'. See section 2.17 Environment Variables Affecting GCC.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.8 Options That Control Optimization

These options control various sorts of optimizations:

-O
-O1
Optimize. Optimizing compilation takes somewhat more time, and a lot more memory for a large function.

Without `-O', the compiler's goal is to reduce the cost of compilation and to make debugging produce the expected results. Statements are independent: if you stop the program with a breakpoint between statements, you can then assign a new value to any variable or change the program counter to any other statement in the function and get exactly the results you would expect from the source code.

Without `-O', the compiler only allocates variables declared register in registers. The resulting compiled code is a little worse than produced by PCC without `-O'.

With `-O', the compiler tries to reduce code size and execution time.

When you specify `-O', the compiler turns on `-fthread-jumps' and
`-fdefer-pop' on all machines. The compiler turns on `-fdelayed-branch' on machines that have delay slots, and `-fomit-frame-pointer' on machines that can support debugging even without a frame pointer. On some machines the compiler also turns on other flags.

-O2
Optimize even more. GCC performs nearly all supported optimizations that do not involve a space-speed tradeoff. The compiler does not perform loop unrolling or function inlining when you specify `-O2'. As compared to `-O', this option increases both compilation time and the performance of the generated code.

`-O2' turns on all optional optimizations except for loop unrolling and function inlining. It also turns on the `-fforce-mem' option on all machines and frame pointer elimination on machines where doing so does not interfere with debugging.

-O3
Optimize yet more. `-O3' turns on all optimizations specified by `-O2' and also turns on the `inline-functions' option.

-O0
Do not optimize.

-Os
Optimize for size. `-Os' enables all `-O2' optimizations that do not typically increase code size. It also performs further optimizations designed to reduce code size.

If you use multiple `-O' options, with or without level numbers, the last such option is the one that is effective.

Options of the form `-fflag' specify machine-independent flags. Most flags have both positive and negative forms; the negative form of `-ffoo' would be `-fno-foo'. In the table below, only one of the forms is listed--the one which is not the default. You can figure out the other form by either removing `no-' or adding it.

-ffloat-store
Do not store floating point variables in registers, and inhibit other options that might change whether a floating point value is taken from a register or memory.

This option prevents undesirable excess precision on machines such as the 68000 where the floating registers (of the 68881) keep more precision than a double is supposed to have. Similarly for the x86 architecture. For most programs, the excess precision does only good, but a few programs rely on the precise definition of IEEE floating point. Use `-ffloat-store' for such programs, after modifying them to store all pertinent intermediate computations into variables.

-fno-default-inline
Do not make member functions inline by default merely because they are defined inside the class scope (C++ only). Otherwise, when you specify `-O', member functions defined inside class scope are compiled inline by default; i.e., you don't need to add `inline' in front of the member function name.

-fno-defer-pop
Always pop the arguments to each function call as soon as that function returns. For machines which must pop arguments after a function call, the compiler normally lets arguments accumulate on the stack for several function calls and pops them all at once.

-fforce-mem
Force memory operands to be copied into registers before doing arithmetic on them. This produces better code by making all memory references potential common subexpressions. When they are not common subexpressions, instruction combination should eliminate the separate register-load. The `-O2' option turns on this option.

-fforce-addr
Force memory address constants to be copied into registers before doing arithmetic on them. This may produce better code just as `-fforce-mem' may.

-fomit-frame-pointer
Don't keep the frame pointer in a register for functions that don't need one. An (optimised) MIPS function will only use a frame pointer when it does something funny with the stack, perhaps because it contains a call to `alloca()' or a variable-length array declaration.

On some machines, such as the Vax, this flag has no effect, because the standard calling sequence automatically handles the frame pointer and nothing is saved by pretending it doesn't exist. The machine-description macro FRAME_POINTER_REQUIRED controls whether a target machine supports this flag. See section `Register Usage' in Using and Porting GCC.

-foptimize-sibling-calls
Optimize sibling and tail recursive calls.

-fno-inline
Don't pay attention to the inline keyword. Normally this option is used to keep the compiler from expanding any functions inline. Note that if you are not optimizing, no functions can be expanded inline.

-finline-functions
Integrate all simple functions into their callers. The compiler heuristically decides which functions are simple enough to be worth integrating in this way.

If all calls to a given function are integrated, and the function is declared static, then the function is normally not output as assembler code in its own right.

-finline-limit=n
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 (ie marked with the inline keyword or defined within the class definition in c++). n is the size of functions that can be inlined in number of pseudo instructions (not counting parameter handling). The default value of n is 10000. Increasing this value can result in more inlined code at the cost of compilation time and memory consumption. Decreasing usually makes the compilation faster and less code will be inlined (which presumably means slower programs). This option is particularly useful for programs that use inlining heavily such as those based on recursive templates with c++.

Note: pseudo instruction represents, in this particular context, an abstract measurement of function's size. In no way, it represents a count of assembly instructions and as such its exact meaning might change from one release to an another.

-fkeep-inline-functions
Even if all calls to a given function are integrated, and the function is declared static, nevertheless output a separate run-time callable version of the function. This switch does not affect extern inline functions.

-fkeep-static-consts
Emit variables declared static const when optimization isn't turned on, even if the variables aren't referenced.

GCC enables this option by default. If you want to force the compiler to check if the variable was referenced, regardless of whether or not optimization is turned on, use the `-fno-keep-static-consts' option.

-fno-function-cse
Do not put function addresses in registers; make each instruction that calls a constant function contain the function's address explicitly.

This option results in less efficient code, but some strange hacks that alter the assembler output may be confused by the optimizations performed when this option is not used.

-ffast-math
This option allows GCC to violate some ANSI or IEEE rules and/or specifications in the interest of optimizing code for speed. For example, it allows the compiler to assume arguments to the sqrt function are non-negative numbers and that no floating-point values are NaNs.

Where the CPU provides fast but non-IEEE-compliant instructions (like MIPS IV's reciprocal and reciprocal square root) the compiler takes this flag as an OK to use them.

This option should never be turned on by any `-O' option since it can result in incorrect output for programs which depend on an exact implementation of IEEE or ANSI rules/specifications for math functions.

-fno-math-errno
Do not set ERRNO after calling math functions that are executed with a single instruction, e.g., sqrt. A program that relies on IEEE exceptions for math error handling may want to use this flag for speed while maintaining IEEE arithmetic compatibility.

The default is `-fmath-errno'. The `-ffast-math' option sets `-fno-math-errno'.

The following options control specific optimizations. The `-O2' option turns on all of these optimizations except `-funroll-loops' and `-funroll-all-loops'. On most machines, the `-O' option turns on the `-fthread-jumps' and `-fdelayed-branch' options, but specific machines may handle it differently.

You can use the following flags in the rare cases when "fine-tuning" of optimizations to be performed is desired.

-fstrength-reduce
Perform the optimizations of loop strength reduction and elimination of iteration variables.

-fthread-jumps
Perform optimizations where we check to see if a jump branches to a location where another comparison subsumed by the first is found. If so, the first branch is redirected to either the destination of the second branch or a point immediately following it, depending on whether the condition is known to be true or false.

-fcse-follow-jumps
In common subexpression elimination, scan through jump instructions when the target of the jump is not reached by any other path. For example, when CSE encounters an if statement with an else clause, CSE will follow the jump when the condition tested is false.

-fcse-skip-blocks
This is similar to `-fcse-follow-jumps', but causes CSE to follow jumps which conditionally skip over blocks. When CSE encounters a simple if statement with no else clause, `-fcse-skip-blocks' causes CSE to follow the jump around the body of the if.

-frerun-cse-after-loop
Re-run common subexpression elimination after loop optimizations has been performed.

-frerun-loop-opt
Run the loop optimizer twice.

-fgcse
Perform a global common subexpression elimination pass. This pass also performs global constant and copy propagation.

-flive-range
Perform live range splitting of variables at loop boundaries. This option is enabled by default at `-O2' optimization and higher for targets which use stabs debug symbols.

-fdelete-null-pointer-checks
Use global dataflow analysis to identify and eliminate useless null pointer checks. Programs which rely on NULL pointer dereferences not halting the program may not work properly with this option. Use -fno-delete-null-pointer-checks to disable this optimizing for programs which depend on that behavior.

-fexpensive-optimizations
Perform a number of minor optimizations that are relatively expensive.

-foptimize-register-moves
-fregmove
Attempt to reassign register numbers in move instructions and as operands of other simple instructions in order to maximize the amount of register tying. This is especially helpful on machines with two-operand instructions. GCC enables this optimization by default with `-O2' or higher.

Note -fregmove and -foptimize-register-moves are the same optimization.

-fdelayed-branch
If supported for the target machine, attempt to reorder instructions to exploit instruction slots available after delayed branch instructions.

-fschedule-insns
If supported for the target machine, attempt to reorder instructions to eliminate execution stalls due to required data being unavailable. This helps machines that have slow floating point or memory load instructions by allowing other instructions to be issued until the result of the load or floating point instruction is required.

-fschedule-insns2
Similar to `-fschedule-insns', but requests an additional pass of instruction scheduling after register allocation has been done. This is especially useful on machines with a relatively small number of registers and where memory load instructions take more than one cycle.

-ffunction-sections
-fdata-sections
Place each function or data item into its own section in the output file if the target supports arbitrary sections. The name of the function or the name of the data item determines the section's name in the output file.

Use these options on systems where the linker can perform optimizations to improve locality of reference in the instruction space. HPPA processors running HP-UX and Sparc processors running Solaris 2 have linkers with such optimizations. Other systems using the ELF object format as well as AIX may have these optimizations in the future.

Only use these options when there are significant benefits from doing so. When you specify these options, the assembler and linker will create larger object and executable files and will also be slower. You will not be able to use gprof on all systems if you specify this option and you may have problems with debugging if you specify both this option and `-g'.

-fcaller-saves
Enable values to be allocated in registers that will be clobbered by function calls, by emitting extra instructions to save and restore the registers around such calls. Such allocation is done only when it seems to result in better code than would otherwise be produced.

This option is always enabled by default on certain machines, usually those which have no call-preserved registers to use instead.

For all machines, optimization level 2 and higher enables this flag by default.

-funroll-loops
Perform the optimization of loop unrolling. This is only done for loops whose number of iterations can be determined at compile time or run time. `-funroll-loops' implies both `-fstrength-reduce' and
`-frerun-cse-after-loop'.

-funroll-all-loops
Perform the optimization of loop unrolling. This is done for all loops and usually makes programs run more slowly. `-funroll-all-loops' implies `-fstrength-reduce' as well as `-frerun-cse-after-loop'.

-fmove-all-movables
Forces all invariant computations in loops to be moved outside the loop.

-freduce-all-givs
Forces all general-induction variables in loops to be strength-reduced.

Note: When compiling programs written in Fortran, `-fmove-all-movables' and `-freduce-all-givs' are enabled by default when you use the optimizer.

These options may generate better or worse code; results are highly dependent on the structure of loops within the source code.

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 (support@mips.com and/or gcc@gcc.gnu.org) know how use of these options affects the performance of your production code. We're very interested in code that runs slower when these options are enabled.

-fno-peephole
Disable any machine-specific peephole optimizations.

-fbranch-probabilities
After running a program compiled with `-fprofile-arcs' (see section Options for Debugging Your Program or gcc), you can compile it a second time using `-fbranch-probabilities', to improve optimizations based on guessing the path a branch might take.

-fstrict-aliasing
Allows the compiler to assume the strictest aliasing rules applicable to the language being compiled. For C (and C++), this activates optimizations based on the type of expressions. In particular, an object of one type is assumed never to reside at the same address as an object of a different type, unless the types are almost the same. For example, an unsigned int can alias an int, but not a void* or a double. A character type may alias any other type.

Pay special attention to code like this:

 
union a_union { 
  int i;
  double d;
};

int f() {
  a_union t;
  t.d = 3.0;
  return t.i;
}
The practice of reading from a different union member than the one most recently written to (called "type-punning") is common. Even with `-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:
 
int f() { 
  a_union t;
  int* ip;
  t.d = 3.0;
  ip = &t.i;
  return *ip;
}

-falign-functions
-falign-functions=n
Align the start of functions to the next power-of-two greater than n, skipping up to n bytes. For instance, `-falign-functions=32' aligns functions to the next 32-byte boundary, but `-falign-functions=24' would align to the next 32-byte boundary only if this can be done by skipping 23 bytes or less.

`-fno-align-functions' and `-falign-functions=1' are equivalent and mean that functions will not be aligned.

Some assemblers only support this flag when n is a power of two; in that case, it is rounded up.

If n is not specified, use a machine-dependent default.

-falign-labels
-falign-labels=n
Align all branch targets to a power-of-two boundary, skipping up to n bytes like `-falign-functions'. This option can easily make code slower, because it must insert dummy operations for when the branch target is reached in the usual flow of the code.

If `-falign-loops' or `-falign-jumps' are applicable and are greater than this value, then their values are used instead.

If n is not specified, use a machine-dependent default which is very likely to be `1', meaning no alignment.

-falign-loops
-falign-loops=n
Align loops to a power-of-two boundary, skipping up to n bytes like `-falign-functions'. The hope is that the loop will be executed many times, which will make up for any execution of the dummy operations.

If n is not specified, use a machine-dependent default.

-falign-jumps
-falign-jumps=n
Align branch targets to a power-of-two boundary, for branch targets where the targets can only be reached by jumping, skipping up to n bytes like `-falign-functions'. In this case, no dummy operations need be executed.

If n is not specified, use a machine-dependent default.

-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. (Currently, no SSA-based optimizations are implemented, but converting into and out of SSA form is not an invariant operation, and generated code may differ.)


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.9 Options Controlling the Preprocessor

These options control the C preprocessor, which is run on each C source file before actual compilation.

If you use the `-E' option, nothing is done except preprocessing. Some of these options make sense only together with `-E' because they cause the preprocessor output to be unsuitable for actual compilation.

-include file
Process file as input before processing the regular input file. In effect, the contents of file are compiled first. Any `-D' and `-U' options on the command line are always processed before `-include file', regardless of the order in which they are written. All the `-include' and `-imacros' options are processed in the order in which they are written.

-imacros file
Process file as input, discarding the resulting output, before processing the regular input file. Because the output generated from file is discarded, the only effect of `-imacros file' is to make the macros defined in file available for use in the main input.

Any `-D' and `-U' options on the command line are always processed before `-imacros file', regardless of the order in which they are written. All the `-include' and `-imacros' options are processed in the order in which they are written.

-idirafter dir
Add the directory dir to the second include path. The directories on the second include path are searched when a header file is not found in any of the directories in the main include path (the one that `-I' adds to).

-iprefix prefix
Specify prefix as the prefix for subsequent `-iwithprefix' options.

-iwithprefix dir
Add a directory to the second include path. The directory's name is made by concatenating prefix and dir, where prefix was specified previously with `-iprefix'. If you have not specified a prefix yet, the directory containing the installed passes of the compiler is used as the default.

-iwithprefixbefore dir
Add a directory to the main include path. The directory's name is made by concatenating prefix and dir, as in the case of `-iwithprefix'.

-isystem dir
Add a directory to the beginning of the second include path, marking it as a system directory, so that it gets the same special treatment as is applied to the standard system directories.

-isystem-c++ dir
Same behavior as with `-isystem', but do not make headers in dir be implicitly evaluated as if they include the `extern "C"' linkage specification.

-nostdinc
Do not search the standard system directories for header files. Only the directories you have specified with `-I' options (and the current directory, if appropriate) are searched. See section 2.12 Options for Directory Search, for information on `-I'.

By using both `-nostdinc' and `-I-', you can limit the include-file search path to only those directories you specify explicitly.

-undef
Do not predefine any nonstandard macros. (Including architecture flags).

-E
Run only the C preprocessor. Preprocess all the C source files specified and output the results to standard output or to the specified output file.

-C
Tell the preprocessor not to discard comments. Used with the `-E' option.

-P
Tell the preprocessor not to generate `#line' directives. Used with the `-E' option.

-M
Tell the preprocessor to output a rule suitable for make describing the dependencies of each object file. For each source file, the preprocessor outputs one make-rule whose target is the object file name for that source file and whose dependencies are all the #include header files it uses. This rule may be a single line or may be continued with `\'-newline if it is long. The list of rules is printed on standard output instead of the preprocessed C program.

`-M' implies `-E'.

Another way to specify output of a make rule is by setting the environment variable DEPENDENCIES_OUTPUT (see section 2.17 Environment Variables Affecting GCC).

-MM
Like `-M' but the output mentions only the user header files included with `#include "file"'. System header files included with `#include <file>' are omitted.

-MD
Like `-M' but the dependency information is written to a file made by replacing ".c" with ".d" at the end of the input file names. This is in addition to compiling the file as specified---`-MD' does not inhibit ordinary compilation the way `-M' does.

In Mach, you can use the utility md to merge multiple dependency files into a single dependency file suitable for using with the `make' command.

-MMD
Like `-MD' except mention only user header files, not system header files.

-MG
Treat missing header files as generated files and assume they live in the same directory as the source file. If you specify `-MG', you must also specify either `-M' or `-MM'. `-MG' is not supported with `-MD' or `-MMD'.

-H
Print the name of each header file used, in addition to other normal activities.

-Aquestion(answer)
Assert the answer answer for question, in case it is tested with a preprocessing conditional such as `#if #question(answer)'. `-A-' disables the standard assertions that normally describe the target machine.

-Dmacro
Define macro macro with the string `1' as its definition.

-Dmacro=defn
Define macro macro as defn. All instances of `-D' on the command line are processed before any `-U' options.

-Umacro
Undefine macro macro. `-U' options are evaluated after all `-D' options, but before any `-include' and `-imacros' options.

-dM
Tell the preprocessor to output only a list of the macro definitions that are in effect at the end of preprocessing. Used with the `-E' option.

-dD
Tell the preprocessing to pass all macro definitions into the output, in their proper sequence in the rest of the output.

-dN
Like `-dD' except that the macro arguments and contents are omitted. Only `#define name' is included in the output.

-trigraphs
Support ANSI C trigraphs. The `-ansi' option also has this effect.

-Wp,option
Pass option as an option to the preprocessor. If option contains commas, it is split into multiple options at the commas.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.10 Passing Options to the Assembler

You can pass options to the assembler.

-Wa,option
Pass option as an option to the assembler. If option contains commas, it is split into multiple options at the commas.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.11 Options for Linking

These options come into play when the compiler links object files into an executable output file. They are meaningless if the compiler is not doing a link step.

object-file-name
A file name that does not end in a special recognized suffix is considered to name an object file or library. (Object files are distinguished from libraries by the linker according to the file contents.) If linking is done, these object files are used as input to the linker.

-c
-S
-E
If any of these options is used, then the linker is not run, and object file names should not be used as arguments. See section 2.2 Options Controlling the Kind of Output.

-llibrary
Search the library named library when linking.

It makes a difference where in the command you write this option; the linker searches processes libraries and object files in the order they are specified. Thus, `foo.o -lz bar.o' searches library `z' after file `foo.o' but before `bar.o'. If `bar.o' refers to functions in `z', those functions may not be loaded.

The linker searches a standard list of directories for the library, which is actually a file named `liblibrary.a'. The linker then uses this file as if it had been specified precisely by name.

The directories searched include several standard system directories plus any that you specify with `-L'.

But since this is a cross-compiler for multiple targets, there are some flags to the compiler which produce incompatible code; the actual library files you used depend on those flags. The "multi-lib" feature puts a different library root directory in the search path to match what your flags have asked for.

The flags which affect the choice of library are:

-EB, -EL
The "endianness" the software is built for.

-mips1, -mips2
Libraries built using the MIPS I instruction set.

-mips3, -mips4
Libraries built using the MIPS III instruction set.

-mips32
Libraries built using MIPS32 instruction set.

-mips32r2
Libraries built using MIPS32 release 2 instruction set.

-mips64, -mips64r2
Libraries built using MIPS64 instruction set.

-mips16, -mips16e
Libraries built using the MIPS16 or MIPS16e instruction set extension, depending on the base ISA.

-mgp32
When combined with `-mips3' or `-mips4' selects libraries built with 32-bit integer registers, but using the full set of 32 64-bit floating-point registers.

-mfp64
When combined with `-mips32r2' only, selects libraries built with 32-bit integer instructions, but using the full set of 32 64-bit floating-point registers, and the MIPS64 extended floating point instructions.

-mno-float
Floating-point-free libraries (smaller).

-msoft-float
Built with all floating-point operations as subroutine calls to a software floating-point emulation library.

-msingle-float
Built using only single-precision floating-point instructions, with double-precision implemented as subroutine calls (like `-msoft-float'); probably only useful for the IDT R4640 and R4650 CPUs.

You might reasonably expect there to be different libraries for `-G0' and `-G8' but there aren't; `-G0' might in theory be less efficient, but the effect is very small and its completely compatible, so all the libraries are built that way.

Normally the files found this way are library files--archive files whose members are object files. The linker handles an archive file by scanning through it for members which define symbols that have so far been referenced but not defined. But if the file that is found is an ordinary object file, it is linked in the usual fashion. The only difference between using an `-l' option and specifying a file name is that `-l' surrounds library with `lib' and `.a' and searches several directories.

-lobjc
You need this special case of the `-l' option in order to link an Objective C program.

-nostartfiles
Do not use the standard system startup files when linking. The standard system libraries are used normally, unless -nostdlib or -nodefaultlibs is used.

-nodefaultlibs
Do not use the standard system libraries when linking. Only the libraries you specify will be passed to the linker. The standard startup files are used normally, unless -nostartfiles is used. The compiler may generate calls to memcmp, memset, and memcpy for System V (and ANSI C) environments or to bcopy and bzero for BSD environments. These entries are usually resolved by entries in libc. These entry points should be supplied through some other mechanism when this option is specified.

-nostdlib
Do not use the standard system startup files or libraries when linking. No startup files and only the libraries you specify will be passed to the linker. The compiler may generate calls to memcmp, memset, and memcpy for System V (and ANSI C) environments or to bcopy and bzero for BSD environments. These entries are usually resolved by entries in libc. These entry points should be supplied through some other mechanism when this option is specified.

One of the standard libraries bypassed by `-nostdlib' and `-nodefaultlibs' is `libgcc.a', a library of internal subroutines that GCC uses to overcome shortcomings of particular machines, or special needs for some languages. (See section `Interfacing to GCC Output' in Porting GCC, for more discussion of `libgcc.a'.) In most cases, you need `libgcc.a' even when you want to avoid other standard libraries. In other words, when you specify `-nostdlib' or `-nodefaultlibs' you should usually specify `-lgcc' as well. This ensures that you have no unresolved references to internal GCC library subroutines.

-s
Remove all symbol table and relocation information from the executable.

-static
On systems that support dynamic linking, this prevents linking with the shared libraries. On other systems, this option has no effect.

-shared
Produce a shared object which can then be linked with other objects to form an executable. Not all systems support this option. You must also specify `-fpic' or `-fPIC' on some systems when you specify this option.

-symbolic
Bind references to global symbols when building a shared object. Warn about any unresolved references (unless overridden by the link editor option `-Xlinker -z -Xlinker defs'). Only a few systems support this option.

-Xlinker option
Pass option as an option to the linker. You can use this to supply system-specific linker options which GCC does not know how to recognize.

If you want to pass an option that takes an argument, you must use `-Xlinker' twice, once for the option and once for the argument. For example, to pass `-assert definitions', you must write `-Xlinker -assert -Xlinker definitions'. It does not work to write `-Xlinker "-assert definitions"', because this passes the entire string as a single argument, which is not what the linker expects.

-Wl,option
Pass option as an option to the linker. If option contains commas, it is split into multiple options at the commas.

-u symbol
Pretend the symbol symbol is undefined, to force linking of library modules to define it. You can use `-u' multiple times with different symbols to force loading of additional library modules.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.12 Options for Directory Search

These options specify directories to search for header files, for libraries and for parts of the compiler:

-Idir
Add the directory dir to the head of the list of directories to be searched for header files. This can be used to override a system header file, substituting your own version, since these directories are searched before the system header file directories. If you use more than one `-I' option, the directories are scanned in left-to-right order; the standard system directories come after.

-I-
Any directories you specify with `-I' options before the `-I-' option are searched only for the case of `#include "file"'; they are not searched for `#include <file>'.

If additional directories are specified with `-I' options after the `-I-', these directories are searched for all `#include' directives. (Ordinarily all `-I' directories are used this way.)

In addition, the `-I-' option inhibits the use of the current directory (where the current input file came from) as the first search directory for `#include "file"'. There is no way to override this effect of `-I-'. With `-I.' you can specify searching the directory which was current when the compiler was invoked. That is not exactly the same as what the preprocessor does by default, but it is often satisfactory.

`-I-' does not inhibit the use of the standard system directories for header files. Thus, `-I-' and `-nostdinc' are independent.

-Ldir
Add directory dir to the list of directories to be searched for `-l'.

-Bprefix
This option specifies where to find the executables, libraries, include files, and data files of the compiler itself.

The compiler driver program runs one or more of the subprograms `cpp', `cc1', `as' and `ld'. It tries prefix as a prefix for each program it tries to run.

For each subprogram to be run, the compiler driver first tries the `-B' prefix, if any. If that name is not found, or if `-B' was not specified, the driver tries two standard prefixes, which are `/usr/lib/gcc/' and
`/usr/local/lib/gcc-lib/'. 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 `PATH' environment variable.

`-B' prefixes that effectively specify directory names also apply to libraries in the linker, because the compiler translates these options into `-L' options for the linker. They also apply to includes files in the preprocessor, because the compiler translates these options into `-isystem' options for the preprocessor. In this case, the compiler appends `include' to the prefix.

The run-time support file `libgcc.a' can also be searched for using the `-B' prefix, if needed. If it is not found there, the two standard prefixes above are tried, and that is all. The file is left out of the link if it is not found by those means.

Another way to specify a prefix much like the `-B' prefix is to use the environment variable GCC_EXEC_PREFIX. See section 2.17 Environment Variables Affecting GCC.

-specs=file
Process file after the compiler reads in the standard `specs' file, in order to override the defaults that the `gcc' driver program uses when determining what switches to pass to `cc1', `cc1plus', `as', `ld', etc. More than one `-specs='file can be specified on the command line, and they are processed in order, from left to right.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.13 Specifying subprocesses and the switches to pass to them

GCC is a driver program. It performs its job by invoking a sequence of other programs to do the work of compiling, assembling and linking. GCC interprets its command-line parameters and uses these to deduce which programs it should invoke, and which command-line options it ought to place on their command lines. This behaviour is controlled by spec strings. In most cases there is one spec string for each program that GCC can invoke, but a few programs have multiple spec strings to control their behaviour. The spec strings built into GCC can be overridden by using the `-specs=' command-line switch to specify a spec file.

Spec files are plaintext files that are used to construct spec strings. They consist of a sequence of directives separated by blank lines. The type of directive is determined by the first non-whitespace character on the line and it can be one of the following:

%command
Issues a command to the spec file processor. The commands that can appear here are:

%include <file>
Search for file and insert its text at the current point in the specs file.

%include_noerr <file>
Just like `%include', but do not generate an error message if the include file cannot be found.

%rename old_name new_name
Rename the spec string old_name to new_name.

*[spec_name]:
This tells the compiler to create, override or delete the named spec string. All lines after this directive up to the next directive or blank line are considered to be the text for the spec string. If this results in an empty string then the spec will be deleted. (Or, if the spec did not exist, then nothing will happened.) Otherwise, if the spec does not currently exist a new spec will be created. If the spec does exist then its contents will be overridden by the text of this directive, unless the first character of that text is the `+' character, in which case the text will be appended to the spec.

[suffix]:
Creates a new `[suffix] spec' pair. All lines after this directive and up to the next directive or blank line are considered to make up the spec string for the indicated suffix. When the compiler encounters an input file with the named suffix, it will processes the spec string in order to work out how to compile that file. For example:

 
.ZZ:
z-compile -input %i

This says that any input file whose name ends in `.ZZ' should be passed to the program `z-compile', which should be invoked with the command-line switch `-input' and with the result of performing the `%i' substitution. (See below.)

As an alternative to providing a spec string, the text that follows a suffix directive can be one of the following:

@language
This says that the suffix is an alias for a known language. This is similar to using the -x command-line switch to GCC to specify a language explicitly. For example:

 
.ZZ:
@c++

Says that .ZZ files are, in fact, C++ source files.

#name
This causes an error messages saying:

 
name compiler not installed on this system.

GCC already has an extensive list of suffixes built into it. This directive will add an entry to the end of the list of suffixes, but since the list is searched from the end backwards, it is effectively possible to override earlier entries using this technique.

GCC has the following spec strings built into it. Spec files can override these strings or create their own. Note that individual targets can also add their own spec strings to this list.

 
asm          Options to pass to the assembler
asm_final    Options to pass to the assembler post-processor
cpp          Options to pass to the C preprocessor
cc1          Options to pass to the C compiler
cc1plus      Options to pass to the C++ compiler
endfile      Object files to include at the end of the link
link         Options to pass to the linker
lib          Libraries to include on the command line to the linker
libgcc       Decides which GCC support library to pass to the linker
linker       Sets the name of the linker
predefines   Defines to be passed to the C preprocessor
signed_char  Defines to pass to CPP to say whether char is signed by default
startfile    Object files to include at the start of the link

Here is a small example of a spec file:

 
%rename lib                 old_lib

*lib:
--start-group -lgcc -lc -leval1 --end-group %(old_lib)

This example renames the spec called `lib' to `old_lib' and then overrides the previous definition of `lib' with a new one. The new definition adds in some extra command-line options before including the text of the old definition.

Spec strings are a list of command-line options to be passed to their corresponding program. In addition, the spec strings can contain `%'-prefixed sequences to substitute variable text or to conditionally insert text into the command line. Using these constructs it is possible to generate quite complex command lines.

Here is a table of all defined `%'-sequences for spec strings. Note that spaces are not generated automatically around the results of expanding these sequences. Therefore you can concatenate them together or combine them with constant text in a single argument.

%%
Substitute one `%' into the program name or argument.

%i
Substitute the name of the input file being processed.

%b
Substitute the basename of the input file being processed. This is the substring up to (and not including) the last period and not including the directory.

%d
Marks the argument containing or following the `%d' as a temporary file name, so that that file will be deleted if GCC exits successfully. Unlike `%g', this contributes no text to the argument.

%gsuffix
Substitute a file name that has suffix suffix and is chosen once per compilation, and mark the argument in the same way as `%d'. To reduce exposure to denial-of-service attacks, the file name is now chosen in a way that is hard to predict even when previously chosen file names are known. For example, `%g.s ... %g.o ... %g.s' might turn into `ccUVUUAU.s ccXYAXZ12.o ccUVUUAU.s'. suffix matches the regexp `[.A-Za-z]*' or the special string `%O', which is treated exactly as if `%O' had been preprocessed. Previously, `%g' was simply substituted with a file name chosen once per compilation, without regard to any appended suffix (which was therefore treated just like ordinary text), making such attacks more likely to succeed.

%usuffix
Like `%g', but generates a new temporary file name even if `%usuffix' was already seen.

%Usuffix
Substitutes the last file name generated with `%usuffix', generating a new one if there is no such last file name. In the absence of any `%usuffix', this is just like `%gsuffix', except they don't share the same suffix space, so `%g.s ... %U.s ... %g.s ... %U.s' would involve the generation of two distinct file names, one for each `%g.s' and another for each `%U.s'. Previously, `%U' was simply substituted with a file name chosen for the previous `%u', without regard to any appended suffix.

%w
Marks the argument containing or following the `%w' as the designated output file of this compilation. This puts the argument into the sequence of arguments that `%o' will substitute later.

%o
Substitutes the names of all the output files, with spaces automatically placed around them. You should write spaces around the `%o' as well or the results are undefined. `%o' is for use in the specs for running the linker. Input files whose names have no recognized suffix are not compiled at all, but they are included among the output files, so they will be linked.

%O
Substitutes the suffix for object files. Note that this is handled specially when it immediately follows `%g, %u, or %U', because of the need for those to form complete file names. The handling is such that `%O' is treated exactly as if it had already been substituted, except that `%g, %u, and %U' do not currently support additional suffix characters following `%O' as they would following, for example, `.o'.

%p
Substitutes the standard macro predefinitions for the current target machine. Use this when running cpp.

%P
Like `%p', but puts `__' before and after the name of each predefined macro, except for macros that start with `__' or with `_L', where L is an uppercase letter. This is for ANSI C.

%I
Substitute a `-iprefix' option made from GCC_EXEC_PREFIX.

%s
Current argument is the name of a library or startup file of some sort. Search for that file in a standard list of directories and substitute the full name found.

%estr
Print str as an error message. str is terminated by a newline. Use this when inconsistent options are detected.

%|
Output `-' if the input for the current command is coming from a pipe.

%(name)
Substitute the contents of spec string name at this point.

%[name]
Like `%(...)' but put `__' around `-D' arguments.

%x{option}
Accumulate an option for `%X'.

%X
Output the accumulated linker options specified by `-Wl' or a `%x' spec string.

%Y
Output the accumulated assembler options specified by `-Wa'.

%Z
Output the accumulated preprocessor options specified by `-Wp'.

%v1
Substitute the major version number of GCC. (For version 2.9.5, this is 2.)

%v2
Substitute the minor version number of GCC. (For version 2.9.5, this is 9.)

%a
Process the asm spec. This is used to compute the switches to be passed to the assembler.

%A
Process the asm_final spec. This is a spec string for passing switches to an assembler post-processor, if such a program is needed.

%l
Process the link spec. This is the spec for computing the command line passed to the linker. Typically it will make use of the `%L %G %S %D and %E' sequences.

%D
Dump out a `-L' option for each directory that GCC believes might contain startup files. If the target supports multilibs then the current multilib directory will be prepended to each of these paths.

%L
Process the lib spec. This is a spec string for deciding which libraries should be included on the command line to the linker.

%G
Process the libgcc spec. This is a spec string for deciding which GCC support library should be included on the command line to the linker.

%S
Process the startfile spec. This is a spec for deciding which object files should be the first ones passed to the linker. Typically this might be a file named `crt0.o'.

%E
Process the endfile spec. This is a spec string that specifies the last object files that will be passed to the linker.

%C
Process the cpp spec. This is used to construct the arguments to be passed to the C preprocessor.

%c
Process the signed_char spec. This is intended to be used to tell cpp whether a char is signed. It typically has the definition:
 
%{funsigned-char:-D__CHAR_UNSIGNED__}

%1
Process the cc1 spec. This is used to construct the options to be passed to the actual C compiler (`cc1').

%2
Process the cc1plus spec. This is used to construct the options to be passed to the actual C++ compiler (`cc1plus').

%*
Substitute the variable part of a matched option. See below. Note that each comma in the substituted string is replaced by a single space.

%{S}
Substitutes the -S switch, if that switch was given to GCC. If that switch was not specified, this substitutes nothing. Note that the leading dash is omitted when specifying this option, and it is automatically inserted if the substitution is performed. Thus the spec string `%{foo}' would match the command-line option `-foo' and would output the command line option `-foo'.

%W{S}
Like %{S} but mark last argument supplied within as a file to be deleted on failure.

%{S*}
Substitutes all the switches specified to GCC whose names start with -S, but which also take an argument. This is used for switches like `-o, -D, -I', etc. GCC considers `-o foo' as being one switch whose names starts with `o'. %{o*} would substitute this text, including the space. Thus two arguments would be generated.

%{^S*}
Like %{S*}, but don't put a blank between a switch and its argument. Thus %{^o*} would only generate one argument, not two.

%{<S}
Remove all occurences of S from the command line. Note - this command is position dependent. `%' commands in the spec string before this option will see S, `%' commands in the spec string after this option will not.

%{S*:X}
Substitutes X if one or more switches whose names start with -S are specified to GCC. Note that the tail part of the -S option (i.e. the part matched by the `*') will be substituted for each occurrence of `%*' within X.

%{S:X}
Substitutes X, but only if the `-S' switch was given to GCC.

%{!S:X}
Substitutes X, but only if the `-S' switch was not given to GCC.

%{|S:X}
Like %{S:X}, but if no S switch, substitute `-'.

%{|!S:X}
Like %{!S:X}, but if there is an S switch, substitute `-'.

%{.S:X}
Substitutes X, but only if processing a file with suffix S.

%{!.S:X}
Substitutes X, but only if not processing a file with suffix S.

%{S|P:X}
Substitutes X if either -S or -P was given to GCC. This may be combined with `!' and `.' sequences as well, although they have a stronger binding than the `|'. For example a spec string like this:

 
%{.c:-foo} %{!.c:-bar} %{.c|d:-baz} %{!.c|d:-boggle}

will output the following command-line options from the following input command-line options:

 
fred.c        -foo -baz
jim.d         -bar -boggle
-d fred.c     -foo -baz -boggle
-d jim.d      -bar -baz -boggle

The conditional text X in a %{S:X} or %{!S:X} construct may contain other nested `%' constructs or spaces, or even newlines. They are processed as usual, as described above.

The `-O, -f, -m, and -W' switches are handled specifically in these constructs. If another value of `-O' or the negated form of a `-f, -m, or -W' switch is found later in the command line, the earlier switch value is ignored, except with {S*} where S is just one letter, which passes all matching options.

The character `|' at the beginning of the predicate text is used to indicate that a command should be piped to the following command, but only if `-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 compiler's spec to say which switches take arguments. But this cannot be done in a consistent fashion. GCC cannot even decide which input files have been specified without knowing which switches take arguments, and it must know which input files to compile in order to tell which compilers to run).

GCC also knows implicitly that arguments starting in `-l' are to be treated as compiler output files, and passed to the linker in their proper position among the other output files.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.14 Specifying Target Machine and Compiler Version

Some GNU C installations allow you to use the same command name to compile for many different targets -- one of them perhaps native applications on your workstation. To manage support, MIPS SDE does not provide this level of option; if you have a different GNU compiler, it will be called `gcc' not `sde-gcc'. MIPS SDE does allow you to select from a large choice of MIPS cross-compilation targets; but that's described in the next section, Different CPUs and Configurations.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.15 Different CPUs and Configurations

The compiler provided with MIPS SDE can generate code for a wide range of MIPS CPUs. Many of these CPU types have a special option, starting with `-m', which configures the compilation process towards that CPU's particular features--for example, R4640 vs R3000, floating-point coprocessor or none. A single installed version of the compiler can compile for any model or configuration, according to the options specified.

These `-m' options are defined for the MIPS family of computers:

-mcpu=cpu_type
Set up the compiler for a particular type or family of CPU. This affects instruction scheduling where the compiler knows about the CPU's timing habits, and produces usually-correct defaults for some of the other options defined below. What it doesn't do is to pick the major instruction set variants, which are set explicitly with options like `-mips3'. Unless you specify otherwise, the compiler will only use the "MIPS I" instruction set of the earliest MIPS CPUs.

Legitimate values for cpu_type are:

r1900, pr1900
Toshiba TX19 CPU core, like `r3900' but with MIPS16.

r2k, r2000
r3k, r3000
Standard MIPS I CPUs.

r3900, pr3900, tx3900
Philips/Toshiba TX39 MIPS I CPU core, with fast multiply-accumulate and branch-likely.

rc32364, rc323xx
IDT 32-bit CPU core -- like `r3000', but with MIPS32-style extensions.

r4k, r4000, r4400
Standard MIPS III CPUs (long pipeline).

4kc, 4km, 4kec, 4kem
MIPS Technologies 4K range of synthesisable MIPS32 and MIPS32 release 2 core CPUs.

4kp, 4kep
MIPS Technologies 4K synthesisable core CPUs with slow multiplier.

4ksc, 4ksd
MIPS Technologies 4KSc and 4KSd synthesisable MIPS32 core CPUs for smartcards, with SmartMIPS extensions.

m4k
MIPS Technologies M4K compact, synthesisable MIPS32 release 2 core CPU.

5kc, 5kf
MIPS Technologies 5K range of synthesisable MIPS64 core CPUs.

24kc, 24kf
MIPS Technologies 24K range of high-performance, synthesisable MIPS32 release 2 core CPUs.

20kc
MIPS Technologies 20Kc dual-issue MIPS64 hard core CPU.

25kf
MIPS Technologies 25Kf dual-issue MIPS64 hard core CPU.

cw400x, cw4001, cw4002, cw4003
LSI miniRISC CPU cores from the CW400x/MR400x families; simple pipeline, LSI-style multiply-accumulate.

cw401x, cw4010, cw4011
LSI CW401x/MR401x family, superscalar miniRISC CPU cores with dual issue and some additional instructions.

atm2, atmizer2, apu
LSI ATMizer-2, a specialised Cw401x CPU for ATM.

tr4101, ev4101
LSI TinyRisc CPU core -- like `cw400x', but with MIPS16.

r4200, vr4200
Standard MIPS III CPUs, but with short pipeline and shared integer/floating-point ALU.

r4100, vr4100
NEC Vr410x MIPS III core -- like `vr4200' but no floating-point.

r4111, vr4111
NEC Vr4111 core -- like `vr4100' but with MIPS16.

r4300, vr4300
NEC Vr4300 MIPS III CPU -- like `vr4200', but faster.

r4320, vr4320
NEC Vr4300 variant, with integer multiply-accumulate.

r4600, r4700
IDT MIPS III CPUs, with short pipeline.

r4640, r4650
IDT R4600 variants, with integer multiply-accumulate, but only single-precision floating-point.

r5k, r5000
R5000 and family, standard MIPS IV CPUs, limited dual-issue of integer and floating-point.

rm52xx, rm5230, rm5260, rm5270
PMC-Sierra RM52xx CPU -- like `r5000' but with integer multiply-accumulate instructions.

r54xx, r5400, r5432, r5464
vr54xx, vr5400, vr5432, vr5464
NEC Vr54xx CPU -- like `r5000' but with integer multiply-accumulate, rotate, multimedia extensions, dual-issue and non-blocking loads.

rc64574, rc64575, rc6457x
IDT 64-bit CPUs -- like `r5000', but with MIPS32-style extensions.

rm7k, rm7000
PMC-Sierra RM70xx CPU -- like `rm52xx' but with dual-issue and non-blocking loads.

r6k, r6000
Ancient MIPS II CPU.

r10k, r10000
Top of the range MIPS IV CPU, with out-of-order execution.

-mips1, -mips2, -mips3, -mips4
The MIPS instruction set has been extended several times, and each major extension is a superset of the one before. Each option tells the compiler to make use of instructions from the appropriate instruction set subset; the default is `-mips1' which uses only the MIPS I instruction set compatible with every MIPS CPU there ever was.

Each instruction set variant has a different default cpu_type; they are `r3000', `r6000', `r4000' and `r5000' respectively.

Although the `-mips2' default CPU is long obsolete, it's still a useful option to build code for a MIPS III CPU when you don't need any 64-bit specific instructions -- roughly equivalent to `-mips3 -mgp32 -mfp32', but your exception handlers don't have to save and restore the full 64-bit register set.

-mips5
Treated identically to `-mips4' by the compiler, which currently has no support for the paired-single vector floating-point format which this instruction set introduced.

-mips32
MIPS Technologies' rationalisation of the 32-bit MIPS instruction set, which at the application level looks a lot like MIPS II with the MIPS IV integer extensions (conditional move, etc), plus multiply-add, multiply-subtract, three-operand multiply, count leading zeroes and ones. This instruction set is likely to be found on an increasing range of 32-bit MIPS-based CPUs and cores, from a number of vendors.

-mips64
MIPS Technologies' rationalisation of the 64-bit MIPS instruction set, which at the application level looks a lot like MIPS IV, plus multiply-add, multiply-subtract, three-operand multiply, count leading zeroes and ones. This instruction set is likely to be found on an increasing range of 64-bit MIPS-based CPUs and cores, from a number of vendors.

-mips32r2, -mips64r2
The release 2 updates to the MIPS32 and MIPS64 architecture add some useful new instructions, including: bit-rotate, bit-field insert/extract, byte swapping, and register sign-extend.

-mips16
MIPS16 is an extension to the base instruction set which provides a subset of true 32-bit MIPS instructions, with a restricted set of registers, and coded as 16-bit instructions. It can make for much smaller program binaries. CPUs supporting MIPS16 switch from interpreting conventional 32-bit MIPS instructions to MIPS16 instructions when they are asked to fetch an instruction from an odd address.

All functions in a C or C++ module built with `-mips16' are compiled using the narrower instructions, unless modified by the `nomips16' function attribute (see section 3.23 Declaring Attributes of Functions). MIPS16 functions may be freely interlinked with true MIPS functions. It is difficult and usually pointless to try to write assembler code for MIPS16; but inside an assembler module you can mix MIPS16 and conventional code using `.set mips16' and `.set nomips16' directives.

MIPS16 CPUs can be either 32-bit or 64-bit implementations. To generate 64-bit MIPS16 code, you should specify a 64-bit base ISA, e.g `-mips3 -mips16'.

-mips16e
MIPS16e is an enhancement of the MIPS16 instruction set, which provides even greater code size reductions. It is only ever available with a MIPS32 or MIPS64 compliant CPU.

Strictly the `-mips16e' option is not required--using the `-mips16' option will generate MIPS16e code if applied as a modifier to `-mips32' or `-mips64'. The only difference is that a `-mips16e' option used on its own will generate MIPS32 code in functions marked with the `nomips16' attribute, whereas `-mips16' would generate MIPS I code.

-msmartmips
SmartMIPS is an extension to the MIPS32 instruction set which provides a number of new instructions which target smartcard and cryptographic applications. The compiler will make use of its rotate and indexed load-word instructions, and the other SmartMIPS instructions can be used in assembler code or C asm expressions.

-mips3D
MIPS-3D is an extension to the MIPS64 instruction set, and is treated identically to `-mips64' by the compiler. The new floating-point instructions can be used in assembler code or C asm expressions.

-mcode-xonly
For MIPS16 code generation only, this flag forces all string constants and jump tables to be placed in the read-only data section, rather than the text/code section. This option is required if you are compiling code for a CPU and virtual memory operating system which mark code pages as "execute only", or a CPU which has separate instruction and data memories. It may result in somewhat larger and slower code. Note that this option does not disable the MIPS16 lwpc instruction, which is still used to load 32-bit immediates from the text section, following the current function--it is handled specially by the CPU, which treats the pc-relative data load as an instruction fetch.

-mno-data-in-code
In MIPS16 code the compiler normally places implicit constants and strings (but not C variables declared with the const attribute) in the `text' section, immediately following the referencing function, where they can be accessed using short PC-relative addresses.

Some MIPS Technologies cores support independent instruction and data memories (SPRAM), which can't read data from the I-memory without special hardware support. Use the `-mno-data-in-code' option when compiling MIPS16 code for a CPU like that. It will produce significantly larger code; so don't use it unless you really need it. When this option is used, it switches off the `-G 0' override which is normally used for MIPS16 code, so that it can place the implicit constants in the small data section and access them via the $gp register. If you specify the `-G 0' option explicitly, then the generated code will get even larger.

-muse-all-regs
For MIPS16 code generation only, this option instructs the compiler to make use of all the general purpose registers, and not just the eight which are directly accessible by MIPS16 code. This may generate better code in some cases, but should be treated as experimental. You probably only want to use this with MIPS16e code, and not the original MIPS16 instruction set, since storing and reloading the additional callee-saved registers in the function prologue/epilogue would be very expensive for vanilla MIPS16.

-mbranch-likely
Allows the use of branch-likely instructions when generating MIPS32 or MIPS64 code. These instructions are officially deprecated and are not used by default when `-mips32' or `-mips64' is selected.

-mfp32
Assume that 32 32-bit floating point registers are available, but only the even-numbered 16 are used for arithmetic (the odd-numbered registers are used quietly by the assembler for loading/storing the high-order bits of double-precision values). This is the default when a 32-bit ISA is specified or implied.

-mfp64
Assume that 32 64-bit floating point registers are available. This is the default when a 64-bit ISA is specified or implied, and is usually illegal with 32-bit ISAs. The exception is that it can be used with `-mips32r2', since MIPS32 release 2 adds new instructions which allow a 32-bit CPU to be combined with a 64-bit FPU.

-mgp32
Assume that the 32 general purpose registers are 32 bits wide. This is the default when a 32-bit ISA is specified or implied. Such code will run correctly on 64-bit MIPS CPUs so long as every function which might call your code is built the same way.

-mgp64
Assume that the general purpose registers are 64 bits wide. This is the default when a 64-bit ISA is specified or implied, and illegal unless your CPU implements a 64-bit instruction set; so it's hard to see when you'd use this option explicitly.

-mcheck-zero-division
-mno-check-zero-division
-mdiv-checks
-mno-div-checks
Do, or don't, generate code to guarantee that integer division by zero will be detected. By default, detection is disabled for MIPS16, but enabled for the 32-bit instruction sets.

For MIPS CPUs the compiler generates code that explicitly checks for zero-valued divisors and traps when one is detected. Use of `-mno-check-zero-division' suppresses such checking.

The `-mdiv-checks' and `-mno-div-checks' flags are simply aliases for (respectively) the `-mcheck-zero-division' and `-mno-check-zero-division' flags, for compatibility with previous versions of MIPS SDE.

-msplit-addresses
-mno-split-addresses
Do, or don't, generate two separate assembler instructions to load the high and low parts of address constants. Defaults to on, which allows the compiler to schedule the two instructions separately and generate more optimal code.

-mrnames
-mno-rnames
The `-mrnames' switch says to output code using the MIPS software names for the registers, instead of the hardware names (ie, $a0 instead of $4). On by default in MIPS SDE, because our version of the GNU assembler is happy with it, and it makes the compiler's assembler output easier to read.

-mgpopt
-mno-gpopt
The `-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.

-mstats
-mno-stats
For each non-inline function processed, the `-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.).

-mmemcpy
-mno-memcpy
The `-mmemcpy' switch makes all block moves call the appropriate string function (`memcpy' or `bcopy') instead of possibly generating inline code. It can reduce the size of your program.

-msoft-float
-mhard-float
-mno-float
Generate output using implicit library calls for floating point, so you can build for machines with no floating point hardware. The floating point emulation library is included in MIPS SDE. `-mhard-float' is the opposite, and it's the default, so rarely specified explicitly.

The `-mno-float' switch implies `-msoft-float' but goes further, by picking optional library variants at link time which don't provide any support for floating point data, and are therefore significantly smaller.

-mslow-mul
Fine-tune the compiler to particular LSI core CPUs (based on `cw401x') which can optionally use a smaller, slower integer multiplier.

-mno-mul
Don't generate integer multiply/divide instructions at all--the compiler will instead insert calls to multiply/divide subroutines. You'll also need to build special libraries compiled with this option (they are not provided with MIPS SDE), or be prepared to catch the "undefined instruction" trap and emulate any multiply/divide instructions which get included from the libraries. The MIPS SDE run-time kit includes a sample instruction emulator.

-mmad
Emit r4650-style mad and mul instructions. Normally the compiler decides whether it can use multiply-add and other extended multiplier features automatically, using the selected CPU type and ISA.

-mconst-mult
Encourages the compiler to use the hardware multiply instruction for all constant multiplications, if the multiply can be accomplished in fewer instructions than the equivalent operation performed inline with shifts and adds. This is the default for MIPS16 code, or if the `-Os' optimization level is selected. In all other cases the compiler will default to preferring a shift/add sequence if that would be faster (rather than smaller) than using the hardware multiplier.

-mno-const-mult
Forces the compiler to change its default for MIPS16 code, or when `-Os' is specified, and use speed rather than space as the constraint on whether to use the hardware multiply instructions.

-membedded-data
-mno-embedded-data
-mgpconst
-mno-gpconst
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.

Note that `-membedded-data' is the default setting for MIPS SDE. Alternatively select `-mno-embedded-data' if you want small constants to be placed in the small data section, instead of the read-only data section, for increased speed.

The `-mno-gpconst' and `-mgpconst' flags are just aliases to the flags
`-membedded-data' and `-mno-embedded-data' respectively, for compatibility with older versions of MIPS SDE.

-muninit-const-in-rodata
-mno-uninit-const-in-rodata
When used together with `-membedded-data', this flag will cause uninitialized const variables to be placed in the read-only data section. The default action is to make uninitialised const variables "common", which places them in the read-write data section.

-mlong-calls
-mno-long-calls
Do all calls with the jalr instruction, which requires loading a function's address into a register before the call. You may need to use this switch if you link a program linked so that a calling function and its matching callee are in separate 256Mbyte segments of memory. But this is would be a bit drastic because it makes all calls much longer and slower. You could use the `longcall' attribute (see section 3.23 Declaring Attributes of Functions) to mark particular functions known to require a long call.

-msingle-float
-mdouble-float
The `-msingle-float' switch tells gcc to assume that the floating point coprocessor only supports single precision operations, as on IDT's R4640 and R4650 CPUs. The `-mdouble-float' switch permits gcc to use double precision operations, and this is the default, even if you specified `-mcpu=r4650'.

-mcommon-prolog
Use built-in subroutines to save/restore registers at function entry and exit, where this would make the code smaller. Can save a significant amount of space, at the cost of a small performance hit if you have lots of little functions. This doesn't work with MIPS16, for which you must use the `-mentry' switch below.

-mentry
Used only with `-mips16', this compresses function entry and exit code by encoding common register save/restore actions into fictional entry/exit instructions. The non-existent instruction codes produce an "unimplemented instruction" trap, and a system using this relies on a trap handler to implement these instructions. The MIPS SDE run-time kit includes a sample entry/exit trap handler.

-EL
Compile code for the processor in little endian mode. The requisite libraries are assumed to exist.

-EB
Compile code for the processor in big endian mode. The requisite libraries are assumed to exist.

-G num
Put global and static items less than or equal to num bytes into special "small data" or "small bss" sections instead of the normal data or bss section. In co-operation with a run-time system which maintains the global pointer register (gp or $28) to point to the accumulated small data items, this allows the assembler to emit one word instruction for variable load/stores.

By default, num is 8, but if your memory map or run-time system will not permit this technique then use `-G 0' to disable the optimisation. You can also increase the value to place more variables into the "fast" sections, but take care not to overflow the 64KB maximum size of the small data region.

The `-G num' switch is also passed to the assembler and linker. All modules must be compiled with the same `-G num' value.

Because GNU C is a mighty undertaking there are options supported by the compiler, but not supported by the rest of the MIPS SDE toolkit. For completeness they are listed here:

-mabi=32
-mabi=o64
-mabi=n32
-mabi=64
-mabi=eabi
-mabi=meabi
Generate code for the indicated ABI. This option should be considered experimental in MIPS SDE. The default is `-mabi=32' in all cases, even when a 64-bit ISA has been selected, and all of the supplied MIPS SDE libraries have been built with the 32-bit ABI.

Note that `-mabi=o64' is a non-standard, undocumented ABI used by some other GNU toolchains for 64-bit code--essentially it's what you get if you stretch `-mabi=32' so that all argument registers and stack parameters are 64-bits wide. We only provide `o64' mode for compatibility with customers with code based that assume that calling convention, but it won't work with the MIPS SDE libraries, and is deprecated.

-mint64
Force long, int and pointer types to be 64 bits wide. This is effective only if a 64-bit ISA is also specified. It is incompatible with the supplied MIPS SDE header files and libraries.

-mlong64
Force long and pointer types to be 64 bits wide, but the int type remains 32 bits wide. This is effective only if a 64-bit ISA is also specified. It is incompatible with the supplied MIPS SDE header files and libraries.

-mlong32
Force long, int, and pointer types to be 32 bits wide.

If none of `-mlong32', `-mlong64', or `-mint64' are set, then the size of ints, longs, and pointers depends on the ABI and ISA chosen. For `-mabi=32', and `-mabi=n32', ints and longs are 32 bits wide. For `-mabi=64', ints are 32 bits, and longs are 64 bits wide. For `-mabi=eabi' and `-mabi=meabi' ints are always 32 bits, but the size of longs tracks the register size of the selected ISA. The width of pointers is always the same as the width of longs.

-mgas
-mmips-as
Generate code for the GNU assembler (the default), or for the old MIPS Computers proprietary assembler. Selecting the old MIPS Computers assembler is unlikely to work well with the MIPS SDE toolchain, which only includes the GNU assembler.

-mhalf-pic
-mno-half-pic
Put pointers to extern references into the data section and load them up, rather than putting the references in the text section. Added to the compiler only for compiling OSF/1 applications. This is unlikely to work correctly with the MIPS SDE toolchain.

-membedded-pic
-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. MIPS SDE uses ELF, so this feature is not supported.

-mabicalls
-mno-abicalls
Emit (or do not emit) the pseudo operations `.abicalls', `.cpload', and `.cprestore' that some Unix systems (such as IRIX, Linux and LynxOS) use for position independent code. In MIPS SDE this option defaults to disabled, but can be enabled if you really know what you are doing.

-mmips-tfile
-mno-mips-tfile
These options relate to the old MIPS ECOFF object code format, and are not supported by MIPS SDE.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.16 Options for Code Generation Conventions

These machine-independent options control the interface conventions used in code generation.

Most of them have both positive and negative forms; the negative form of `-ffoo' would be `-fno-foo'. In the table below, only one of the forms is listed--the one which is not the default. You can figure out the other form by either removing `no-' or adding it.

This level of control is not really compatible with use of a bundled system like MIPS SDE. Some of the options documented here will break compatibility with the MIPS SDE libraries or other parts of the toolchain.

-fexceptions
Enable exception handling. Generates extra code needed to propagate exceptions. For some targets, this implies GNU CC will generate frame unwind information for all functions, which can produce significant data size overhead, although it does not affect execution. If you do not specify this option, GNU CC will enable it by default for languages like C++ which normally require exception handling, and disable it for languages like C that do not normally require it. However, you may need to enable this option when compiling C code that needs to interoperate properly with exception handlers written in C++. You may also wish to disable this option if you are compiling older C++ programs that don't use exception handling.

-funwind-tables
Similar to -fexceptions, except that it will just generate any needed static data, but will not affect the generated code in any other way. You will normally not enable this option; instead, a language processor that needs this handling would enable it on your behalf.

-fpcc-struct-return
Return "short" struct and union values in memory like longer ones, rather than in registers. This convention is less efficient, but it has the advantage of allowing intercallability between GCC-compiled files and files compiled with other compilers.

The precise convention for returning structures in memory depends on the target configuration macros.

Short structures and unions are those whose size and alignment match that of some integer type.

-freg-struct-return
Use the convention that struct and union values are returned in registers when possible. This is more efficient for small structures than `-fpcc-struct-return'.

If you specify neither `-fpcc-struct-return' nor its contrary `-freg-struct-return', GCC defaults to whichever convention is standard for the target. If there is no standard convention, GCC defaults to `-fpcc-struct-return', except on targets where GCC is the principal compiler. In those cases, we can choose the standard, and we chose the more efficient register return alternative.

-fshort-enums
Allocate to an enum type only as many bytes as it needs for the declared range of possible values. Specifically, the enum type will be equivalent to the smallest integer type which has enough room.

-fshort-double
Use the same size for double as for float.

-fno-common
Allocate even uninitialized global variables in the data section of the object file, rather than generating them as common blocks. This has the effect that if the same variable is declared (without extern) in two different compilations, you will get an error when you link them.

This setting is the default for MIPS16 code generation, since it allows more efficient access to locally defined variables. If that breaks your code then you can either use the "common" attribute on individual variables (see section 3.29 Specifying Attributes of Variables), or use the positive `-fcommon' flag to override this globally.

-fno-ident
Ignore the `#ident' directive.

-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 collect2 program to make sure the system linker includes constructors and destructors. (collect2 is included in the GCC distribution.) For systems which must use collect2, the compiler driver gcc is configured to do this automatically.

-finhibit-size-directive
Don't output a .size assembler directive, or anything else that would cause trouble if the function is split in the middle, and the two halves are placed at locations far apart in memory. This option is used when compiling `crtstuff.c'; you should not need to use it for anything else.

-fverbose-asm
Put extra commentary information in the generated assembly code to make it more readable. This option is generally only of use to those who actually need to read the generated assembly code (perhaps while debugging the compiler itself).

`-fno-verbose-asm', the default, causes the extra information to be omitted and is useful when comparing two assembler files.

-fvolatile
Consider all memory references through pointers to be volatile.

-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.

-fvolatile-static
Consider all memory references to static data to be volatile.

-fpic
Generate position-independent code (PIC) suitable for use in a shared library, if supported for the target machine. Such code accesses all constant addresses through a global offset table (GOT). The dynamic loader resolves the GOT entries when the program starts (the dynamic 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 `-fpic' does not work; in that case, recompile with `-fPIC' instead. (These maximums are 16k on the m88k, 8k on the Sparc, and 32k on the m68k, RS/6000 and MIPS. The 386 has no such limit.)

Position-independent code requires special support, and therefore works only on certain machines and operating systems.

-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, and the Sparc.

Position-independent code requires special support, and therefore works only on certain machines and operating systems.

-ffixed-reg
Treat the register named reg as a fixed register; generated code should never refer to it (except perhaps as a stack pointer, frame pointer or in some other fixed role).

reg must be the name of a register. The register names accepted are machine-specific. For MIPS they are the register number, optionally preceded by a `$' (e.g. $4), or the software name of the register, again optionally preceded by a `$' (e.g. $a0).

This flag does not have a negative form, because it specifies a three-way choice.

-fcall-used-reg
Treat the register named reg as an allocable register that is clobbered by function calls. It may be allocated for temporaries or variables that do not live across a call. Functions compiled this way will not save and restore the register reg.

It is an error to used this flag with the frame pointer or stack pointer. Use of this flag for other registers that have fixed pervasive roles in the machine's execution model will produce disastrous results.

This flag does not have a negative form, because it specifies a three-way choice.

-fcall-saved-reg
Treat the register named reg as an allocable register saved by functions. It may be allocated even for temporaries or variables that live across a call. Functions compiled this way will save and restore the register reg if they use it.

It is an error to used this flag with the frame pointer or stack pointer. Use of this flag for other registers that have fixed pervasive roles in the machine's execution model will produce disastrous results.

A different sort of disaster will result from the use of this flag for a register in which function values may be returned.

This flag does not have a negative form, because it specifies a three-way choice.

-fpack-struct
Pack all structure members together without holes. Usually you would not want to use this option, since it makes the code suboptimal, and the offsets of structure members won't agree with system libraries.

-fcheck-memory-usage
Generate extra code to check each memory access. GCC will generate code that is suitable for a detector of bad memory accesses such as `Checker'.

Normally, you should compile all, or none, of your code with this option.

If you do mix code compiled with and without this option, you must ensure that all code that has side effects and that is called by code compiled with this option is, itself, compiled with this option. If you do not, you might get erroneous messages from the detector.

If you use functions from a library that have side-effects (such as read), you might not be able to recompile the library and specify this option. In that case, you can enable the `-fprefix-function-name' option, which requests GCC to encapsulate your code and make other functions look as if they were compiled with `-fcheck-memory-usage'. This is done by calling "stubs", which are provided by the detector. If you cannot find or build stubs for every function you call, you might have to specify `-fcheck-memory-usage' without `-fprefix-function-name'.

If you specify this option, you can not use the asm or __asm__ keywords in functions with memory checking enabled. GNU CC cannot understand what the asm statement may do, and therefore cannot generate the appropriate code, so it will reject it. However, if you specify the function attribute no_check_memory_usage (see see section 3.23 Declaring Attributes of Functions, GNU CC will disable memory checking within a function; you may use asm statements inside such functions. You may have an inline expansion of a non-checked function within a checked function; in that case GNU CC will not generate checks for the inlined function's memory accesses.

If you move your asm statements to non-checked inline functions and they do access memory, you can add calls to the support code in your inline function, to indicate any reads, writes, or copies being done. These calls would be similar to those done in the stubs described above.

-fprefix-function-name
Request GCC to add a prefix to the symbols generated for function names. GCC adds a prefix to the names of functions defined as well as functions called. Code compiled with this option and code compiled without the option can't be linked together, unless stubs are used.

If you compile the following code with `-fprefix-function-name'

 
extern void bar (int);
void
foo (int a)
{
  return bar (a + 5);
}

GCC will compile the code as if it was written:

 
extern void prefix_bar (int);
void
prefix_foo (int a)
{
  return prefix_bar (a + 5);
}
This option is designed to be used with `-fcheck-memory-usage'.

-finstrument-functions
Generate instrumentation calls for entry and exit to functions. Just after function entry and just before function exit, the following profiling functions will be called with the address of the current function and its call site. (On some platforms, __builtin_return_address does not work beyond the current function, so the call site information may not be available to the profiling functions otherwise.)

 
void __cyg_profile_func_enter (void *this_fn, void *call_site);
void __cyg_profile_func_exit  (void *this_fn, void *call_site);

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 `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.)

A function may be given the attribute no_instrument_function, in which case this instrumentation will not be done. This can be used, for example, for the profiling functions listed above, high-priority interrupt routines, and any functions from which the profiling functions cannot safely be called (perhaps signal handlers, if the profiling routines generate output or allocate memory).

-fstack-check
Generate code to verify that you do not go beyond the boundary of the stack. You should specify this flag if you are running in an environment with multiple threads, but only rarely need to specify it in a single-threaded environment since stack overflow is automatically detected on nearly all systems if there is only one stack.

Note that this switch does not actually cause checking to be done; the operating system must do that. The switch causes generation of code to ensure that the operating system sees the stack being extended.

-fstack-limit-register=reg
-fstack-limit-symbol=sym
-fno-stack-limit
Generate code to ensure that the stack does not grow beyond a certain value, either the value of a register or the address of a symbol. If the stack would grow beyond the value, a signal is raised. For most targets, the signal is raised before the stack overruns the boundary, so it is possible to catch the signal without taking special precautions.

For instance, if the stack starts at address `0x80000000' and grows downwards you can use the flags `-fstack-limit-symbol=__stack_limit' and
`-Wl,--defsym,__stack_limit=0x7ffe0000' which will enforce a stack limit of 128K.

-funaligned-pointers
Assume that all pointers contain unaligned addresses. On machines where unaligned memory accesses trap, this will result in much larger and slower code for all pointer dereferences, but the code will work even if addresses are unaligned.

-funaligned-struct-hack
Always access structure fields using loads and stores of the declared size. This option is useful for code that derefences pointers to unaligned structures, but only accesses fields that are themselves aligned. Without this option, gcc may try to use a memory access larger than the field. This might give an unaligned access fault on some hardware.

This option makes some invalid code work at the expense of disabling some optimizations. It is strongly recommended that this option not be used.

-foptimize-comparisons
Optimize multiple comparisons better within && and || expressions. This is an experimental option. In some cases it can result in worse code. It depends on many factors. Now it is known only that the optimization works well for PPC740 and PPC750. This option switches on the following transformations:
 
  (a != 0 || b != 0)  =>  ((a | b) != 0)
  (a == 0 && b == 0)  =>  ((a | b) == 0)
  (a != b || c != d)  =>  (((a ^ b) | (c ^ d)) != 0)
  (a == b && c == d)  =>  (((a ^ b) | (c ^ d)) == 0)
  (a != 0 && b != 0)  =>  (((a | -a) & (b | -b)) < 0)
  (a != b && c != d)  =>  x = a ^ b; y = c ^ d; 
                          (((x | -x) & (y | -y)) < 0)
  (a < 0 || b < 0)    =>  ((a | b) < 0)
  (a < 0 && b < 0)    =>  ((a & b) < 0)
  (a >= 0 || b >= 0)  =>  ((a & b) >= 0)
  (a >= 0 && b >= 0)  =>  ((a | b) >= 0)
  (a < 0 || b >= 0)   =>  ((a | ~b) < 0)
  (a < 0 && b >= 0)   =>  ((a & ~b) < 0)
  (a >= 0 || b < 0)   =>  ((~a | b) < 0)
  (a >= 0 && b < 0)   =>  ((~a & b) < 0)
  (a != 0 && b < 0)   =>  (((a | -a) & b) < 0)
  (a != 0 && b >= 0)  =>  (((a | -a) & ~b) < 0)
  (a < 0 && b != 0)   =>  (((b | -b) & a) < 0)
  (a >= 0 && b != 0)  =>  (((b | -b) & ~a) < 0)

-fargument-alias
-fargument-noalias
-fargument-noalias-global
Specify the possible relationships among parameters and between parameters and global data.

`-fargument-alias' specifies that arguments (parameters) may alias each other and may alias global storage. `-fargument-noalias' specifies that arguments do not alias each other, but may alias global storage. `-fargument-noalias-global' specifies that arguments do not alias each other and do not alias global storage.

Each language will automatically use whatever option is required by the language standard. You should not need to use these options yourself.

-fleading-underscore
This option and its counterpart, -fno-leading-underscore, forcibly change the way C symbols are represented in the object file. One use is to help link with legacy assembly code.

Be warned that you should know what you are doing when invoking this option, and that not all targets provide complete support for it.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.17 Environment Variables Affecting GCC

This section describes several environment variables that affect how GCC operates. Some of them work by specifying directories or prefixes to use when searching for various kinds of files. Some are used to specify other aspects of the compilation environment.

Note that you can also specify places to search using options such as `-B', `-I' and `-L' (see section 2.12 Options for Directory Search). These take precedence over places specified using environment variables, which in turn take precedence over those specified by the configuration of GCC.

LANG
LC_CTYPE
LC_MESSAGES
LC_ALL
These environment variables control the way that GCC uses localization information that allow GCC to work with different national conventions. GCC inspects the locale categories LC_CTYPE and LC_MESSAGES if it has been configured to do so. These locale categories can be set to any value supported by your installation. A typical value is `en_UK' for English in the United Kingdom.

The LC_CTYPE environment variable specifies character classification. GCC uses it to determine the character boundaries in a string; this is needed for some multibyte encodings that contain quote and escape characters that would otherwise be interpreted as a string end or escape.

The LC_MESSAGES environment variable specifies the language to use in diagnostic messages.

If the LC_ALL environment variable is set, it overrides the value of LC_CTYPE and LC_MESSAGES; otherwise, LC_CTYPE and LC_MESSAGES default to the value of the LANG environment variable. If none of these variables are set, GCC defaults to traditional C English behavior.

TMPDIR
If TMPDIR is set, it specifies the directory to use for temporary files. GCC uses temporary files to hold the output of one stage of compilation which is to be used as input to the next stage: for example, the output of the preprocessor, which is the input to the compiler proper.

GCC_EXEC_PREFIX
If GCC_EXEC_PREFIX is set, it specifies a prefix to use in the names of the subprograms executed by the compiler. No slash is added when this prefix is combined with the name of a subprogram, but you can specify a prefix that ends with a slash if you wish.

If GCC_EXEC_PREFIX is not set, GNU CC will attempt to figure out an appropriate prefix to use based on the pathname it was invoked with.

If GCC cannot find the subprogram using the specified prefix, it tries looking in the usual places for the subprogram.

The default value of GCC_EXEC_PREFIX is `prefix/lib/gcc-lib/' where prefix is the value of prefix when you ran the `configure' script.

Other prefixes specified with `-B' take precedence over this prefix.

This prefix is also used for finding files such as `crt0.o' that are 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 `/usr/local/lib/gcc-lib' (more precisely, with the value of GCC_INCLUDE_DIR), GCC tries replacing that beginning with the specified prefix to produce an alternate directory name. Thus, with `-Bfoo/', GCC will search `foo/bar' where it would normally search `/usr/local/lib/bar'. These alternate directories are searched first; the standard directories come next.

COMPILER_PATH
The value of COMPILER_PATH is a colon-separated list of directories, much like PATH. GCC tries the directories thus specified when searching for subprograms, if it can't find the subprograms using GCC_EXEC_PREFIX.

LIBRARY_PATH
The value of LIBRARY_PATH is a colon-separated list of directories, much like PATH. When configured as a native compiler, GCC tries the directories thus specified when searching for special linker files, if it can't find them using GCC_EXEC_PREFIX. Linking using GCC also uses these directories when searching for ordinary libraries for the `-l' option (but directories specified with `-L' come first).

C_INCLUDE_PATH
CPLUS_INCLUDE_PATH
OBJC_INCLUDE_PATH
These environment variables pertain to particular languages. Each variable's value is a colon-separated list of directories, much like PATH. When GCC searches for header files, it tries the directories listed in the variable for the language you are using, after the directories specified with `-I' but before the standard header file directories.

DEPENDENCIES_OUTPUT
If this variable is set, its value specifies how to output dependencies for Make based on the header files processed by the compiler. This output looks much like the output from the `-M' option (see section 2.9 Options Controlling the Preprocessor), but it goes to a separate file, and is in addition to the usual results of compilation.

The value of DEPENDENCIES_OUTPUT can be just a file name, in which case the Make rules are written to that file, guessing the target name from the source file name. Or the value can have the form `file target', in which case the rules are written to file file using target as the target name.

LANG
This variable is used to pass locale information to the compiler. One way in which this information is used is to determine the character set to be used when character literals, string literals and comments are parsed in C and C++. When the compiler is configured to allow multibyte characters, the following values for LANG are recognized:

C-JIS
Recognize JIS characters.
C-SJIS
Recognize SJIS characters.
C-EUCJP
Recognize EUCJP characters.

If LANG is not defined, or if it has some other value, then the compiler will use mblen and mbtowc as defined by the default locale to recognize and translate multibyte characters.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.18 Running Protoize

The program protoize is an optional part of GNU C. You can use it to add prototypes to a program, thus converting the program to ANSI C in one respect. The companion program unprotoize does the reverse: it removes argument types from any prototypes that are found.

When you run these programs, you must specify a set of source files as command line arguments. The conversion programs start out by compiling these files to see what functions they define. The information gathered about a file foo is saved in a file named `foo.X'.

After scanning comes actual conversion. The specified files are all eligible to be converted; any files they include (whether sources or just headers) are eligible as well.

But not all the eligible files are converted. By default, protoize and unprotoize convert only source and header files in the current directory. You can specify additional directories whose files should be converted with the `-d directory' option. You can also specify particular files to exclude with the `-x file' option. A file is converted if it is eligible, its directory name matches one of the specified directory names, and its name within the directory has not been excluded.

Basic conversion with protoize consists of rewriting most function definitions and function declarations to specify the types of the arguments. The only ones not rewritten are those for varargs functions.

protoize optionally inserts prototype declarations at the beginning of the source file, to make them available for any calls that precede the function's definition. Or it can insert prototype declarations with block scope in the blocks where undeclared functions are called.

Basic conversion with unprotoize consists of rewriting most function declarations to remove any argument types, and rewriting function definitions to the old-style pre-ANSI form.

Both conversion programs print a warning for any function declaration or definition that they can't convert. You can suppress these warnings with `-q'.

The output from protoize or unprotoize replaces the original source file. The original file is renamed to a name ending with `.save' (for DOS, the saved filename ends in `.sav' without the original `.c' suffix). If the `.save' (`.sav' for DOS) file already exists, then the source file is simply discarded.

protoize and unprotoize both depend on GCC itself to scan the program and collect information about the functions it uses. So neither of these programs will work until GCC is installed.

Here is a table of the options you can use with protoize and unprotoize. Each option works with both programs unless otherwise stated.

-B directory
Look for the file `SYSCALLS.c.X' in directory, instead of the usual directory (normally `/usr/local/lib'). This file contains prototype information about standard system functions. This option applies only to protoize.

-c compilation-options
Use compilation-options as the options when running gcc to produce the `.X' files. The special option `-aux-info' is always passed in addition, to tell gcc to write a `.X' file.

Note that the compilation options must be given as a single argument to protoize or unprotoize. If you want to specify several gcc options, you must quote the entire set of compilation options to make them a single word in the shell.

There are certain gcc arguments that you cannot use, because they would produce the wrong kind of output. These include `-g', `-O', `-c', `-S', and `-o' If you include these in the compilation-options, they are ignored.

-C
Rename files to end in `.C' (`.cc' for DOS-based file systems) instead of `.c'. This is convenient if you are converting a C program to C++. This option applies only to protoize.

-g
Add explicit global declarations. This means inserting explicit declarations at the beginning of each source file for each function that is called in the file and was not declared. These declarations precede the first function definition that contains a call to an undeclared function. This option applies only to protoize.

-i string
Indent old-style parameter declarations with the string string. This option applies only to protoize.

unprotoize converts prototyped function definitions to old-style function definitions, where the arguments are declared between the argument list and the initial `{'. By default, unprotoize uses five spaces as the indentation. If you want to indent with just one space instead, use `-i " "'.

-k
Keep the `.X' files. Normally, they are deleted after conversion is finished.

-l
Add explicit local declarations. protoize with `-l' inserts a prototype declaration for each function in each block which calls the function without any declaration. This option applies only to protoize.

-n
Make no real changes. This mode just prints information about the conversions that would have been done without `-n'.

-N
Make no `.save' files. The original files are simply deleted. Use this option with caution.

-p program
Use the program program as the compiler. Normally, the name `gcc' is used.

-q
Work quietly. Most warnings are suppressed.

-v
Print the version number, just like `-v' for gcc.

If you need special compiler options to compile one of your program's source files, then you should generate that file's `.X' file specially, by running gcc on that source file with the appropriate options and the option `-aux-info'. Then run protoize on the entire set of files. protoize will use the existing `.X' file because it is newer than the source file. For example:

 
gcc -Dfoo=bar file1.c -aux-info
protoize *.c

You need to include the special files along with the rest in the protoize command, even though their `.X' files already exist, because otherwise they won't get converted.

See section 6.7 Caveats of using protoize, for more information on how to use protoize successfully.


[ << ] [ >> ]           [Top] [Contents] [Index] [ ? ]

This document was generated by MIPS Technologies, Inc. on September, 12 2003 using texi2html