red registers as if this option was not present. `-madjust-unroll' Throttle unrolling to avoid thrashing target registers. This option only has an effect if the gcc code base supports the TARGET_ADJUST_UNROLL_MAX target hook. `-mindexed-addressing' Enable the use of the indexed addressing mode for SHmedia32/SHcompact. This is only safe if the hardware and/or OS implement 32 bit wrap-around semantics for the indexed addressing mode. The architecture allows the implementation of processors with 64 bit MMU, which the OS could use to get 32 bit addressing, but since no current hardware implementation supports this or any other way to make the indexed addressing mode safe to use in the 32 bit ABI, the default is -mno-indexed-addressing. `-mgettrcost=NUMBER' Set the cost assumed for the gettr instruction to NUMBER. The default is 2 if `-mpt-fixed' is in effect, 100 otherwise. `-mpt-fixed' Assume pt* instructions won't trap. This will generally generate better scheduled code, but is unsafe on current hardware. The current architecture definition says that ptabs and ptrel trap when the target anded with 3 is 3. This has the unintentional effect of making it unsafe to schedule ptabs / ptrel before a branch, or hoist it out of a loop. For example, __do_global_ctors, a part of libgcc that runs constructors at program startup, calls functions in a list which is delimited by -1. With the -mpt-fixed option, the ptabs will be done before testing against -1. That means that all the constructors will be run a bit quicker, but when the loop comes to the end of the list, the program crashes because ptabs loads -1 into a target register. Since this option is unsafe for any hardware implementing the current architecture specification, the default is -mno-pt-fixed. Unless the user specifies a specific cost with `-mgettrcost', -mno-pt-fixed also implies `-mgettrcost=100'; this deters register allocation using target registers for storing ordinary integers. `-minvalid-symbols' Assume symbols might be invalid. Ordinary function symbols generated by the compiler will always be valid to load with movi/shori/ptabs or movi/shori/ptrel, but with assembler and/or linker tricks it is possible to generate symbols that will cause ptabs / ptrel to trap. This option is only meaningful when `-mno-pt-fixed' is in effect. It will then prevent cross-basic-block cse, hoisting and most scheduling of symbol loads. The default is `-mno-invalid-symbols'.  File: gcc.info, Node: SPARC Options, Next: SPU Options, Prev: SH Options, Up: Submodel Options 3.17.31 SPARC Options --------------------- These `-m' options are supported on the SPARC: `-mno-app-regs' `-mapp-regs' Specify `-mapp-regs' to generate output using the global registers 2 through 4, which the SPARC SVR4 ABI reserves for applications. This is the default. To be fully SVR4 ABI compliant at the cost of some performance loss, specify `-mno-app-regs'. You should compile libraries and system software with this option. `-mfpu' `-mhard-float' Generate output containing floating point instructions. This is the default. `-mno-fpu' `-msoft-float' Generate output containing library calls for floating point. *Warning:* the requisite libraries are not available for all SPARC targets. Normally the facilities of the machine's usual C compiler are used, but this cannot be done directly in cross-compilation. You must make your own arrangements to provide suitable library functions for cross-compilation. The embedded targets `sparc-*-aout' and `sparclite-*-*' do provide software floating point support. `-msoft-float' changes the calling convention in the output file; therefore, it is only useful if you compile _all_ of a program with this option. In particular, you need to compile `libgcc.a', the library that comes with GCC, with `-msoft-float' in order for this to work. `-mhard-quad-float' Generate output containing quad-word (long double) floating point instructions. `-msoft-quad-float' Generate output containing library calls for quad-word (long double) floating point instructions. The functions called are those specified in the SPARC ABI. This is the default. As of this writing, there are no SPARC implementations that have hardware support for the quad-word floating point instructions. They all invoke a trap handler for one of these instructions, and then the trap handler emulates the effect of the instruction. Because of the trap handler overhead, this is much slower than calling the ABI library routines. Thus the `-msoft-quad-float' option is the default. `-mno-unaligned-doubles' `-munaligned-doubles' Assume that doubles have 8 byte alignment. This is the default. With `-munaligned-doubles', GCC assumes that doubles have 8 byte alignment only if they are contained in another type, or if they have an absolute address. Otherwise, it assumes they have 4 byte alignment. Specifying this option avoids some rare compatibility problems with code generated by other compilers. It is not the default because it results in a performance loss, especially for floating point code. `-mno-faster-structs' `-mfaster-structs' With `-mfaster-structs', the compiler assumes that structures should have 8 byte alignment. This enables the use of pairs of `ldd' and `std' instructions for copies in structure assignment, in place of twice as many `ld' and `st' pairs. However, the use of this changed alignment directly violates the SPARC ABI. Thus, it's intended only for use on targets where the developer acknowledges that their resulting code will not be directly in line with the rules of the ABI. `-mimpure-text' `-mimpure-text', used in addition to `-shared', tells the compiler to not pass `-z text' to the linker when linking a shared object. Using this option, you can link position-dependent code into a shared object. `-mimpure-text' suppresses the "relocations remain against allocatable but non-writable sections" linker error message. However, the necessary relocations will trigger copy-on-write, and the shared object is not actually shared across processes. Instead of using `-mimpure-text', you should compile all source code with `-fpic' or `-fPIC'. This option is only available on SunOS and Solaris. `-mcpu=CPU_TYPE' Set the instruction set, register set, and instruction scheduling parameters for machine type CPU_TYPE. Supported values for CPU_TYPE are `v7', `cypress', `v8', `supersparc', `sparclite', `f930', `f934', `hypersparc', `sparclite86x', `sparclet', `tsc701', `v9', `ultrasparc', `ultrasparc3', `niagara' and `niagara2'. Default instruction scheduling parameters are used for values that select an architecture and not an implementation. These are `v7', `v8', `sparclite', `sparclet', `v9'. Here is a list of each supported architecture and their supported implementations. v7: cypress v8: supersparc, hypersparc sparclite: f930, f934, sparclite86x sparclet: tsc701 v9: ultrasparc, ultrasparc3, niagara, niagara2 By default (unless configured otherwise), GCC generates code for the V7 variant of the SPARC architecture. With `-mcpu=cypress', the compiler additionally optimizes it for the Cypress CY7C602 chip, as used in the SPARCStation/SPARCServer 3xx series. This is also appropriate for the older SPARCStation 1, 2, IPX etc. With `-mcpu=v8', GCC generates code for the V8 variant of the SPARC architecture. The only difference from V7 code is that the compiler emits the integer multiply and integer divide instructions which exist in SPARC-V8 but not in SPARC-V7. With `-mcpu=supersparc', the compiler additionally optimizes it for the SuperSPARC chip, as used in the SPARCStation 10, 1000 and 2000 series. With `-mcpu=sparclite', GCC generates code for the SPARClite variant of the SPARC architecture. This adds the integer multiply, integer divide step and scan (`ffs') instructions which exist in SPARClite but not in SPARC-V7. With `-mcpu=f930', the compiler additionally optimizes it for the Fujitsu MB86930 chip, which is the original SPARClite, with no FPU. With `-mcpu=f934', the compiler additionally optimizes it for the Fujitsu MB86934 chip, which is the more recent SPARClite with FPU. With `-mcpu=sparclet', GCC generates code for the SPARClet variant of the SPARC architecture. This adds the integer multiply, multiply/accumulate, integer divide step and scan (`ffs') instructions which exist in SPARClet but not in SPARC-V7. With `-mcpu=tsc701', the compiler additionally optimizes it for the TEMIC SPARClet chip. With `-mcpu=v9', GCC generates code for the V9 variant of the SPARC architecture. This adds 64-bit integer and floating-point move instructions, 3 additional floating-point condition code registers and conditional move instructions. With `-mcpu=ultrasparc', the compiler additionally optimizes it for the Sun UltraSPARC I/II/IIi chips. With `-mcpu=ultrasparc3', the compiler additionally optimizes it for the Sun UltraSPARC III/III+/IIIi/IIIi+/IV/IV+ chips. With `-mcpu=niagara', the compiler additionally optimizes it for Sun UltraSPARC T1 chips. With `-mcpu=niagara2', the compiler additionally optimizes it for Sun UltraSPARC T2 chips. `-mtune=CPU_TYPE' Set the instruction scheduling parameters for machine type CPU_TYPE, but do not set the instruction set or register set that the option `-mcpu=CPU_TYPE' would. The same values for `-mcpu=CPU_TYPE' can be used for `-mtune=CPU_TYPE', but the only useful values are those that select a particular cpu implementation. Those are `cypress', `supersparc', `hypersparc', `f930', `f934', `sparclite86x', `tsc701', `ultrasparc', `ultrasparc3', `niagara', and `niagara2'. `-mv8plus' `-mno-v8plus' With `-mv8plus', GCC generates code for the SPARC-V8+ ABI. The difference from the V8 ABI is that the global and out registers are considered 64-bit wide. This is enabled by default on Solaris in 32-bit mode for all SPARC-V9 processors. `-mvis' `-mno-vis' With `-mvis', GCC generates code that takes advantage of the UltraSPARC Visual Instruction Set extensions. The default is `-mno-vis'. These `-m' options are supported in addition to the above on SPARC-V9 processors in 64-bit environments: `-mlittle-endian' Generate code for a processor running in little-endian mode. It is only available for a few configurations and most notably not on Solaris and Linux. `-m32' `-m64' Generate code for a 32-bit or 64-bit environment. The 32-bit environment sets int, long and pointer to 32 bits. The 64-bit environment sets int to 32 bits and long and pointer to 64 bits. `-mcmodel=medlow' Generate code for the Medium/Low code model: 64-bit addresses, programs must be linked in the low 32 bits of memory. Programs can be statically or dynamically linked. `-mcmodel=medmid' Generate code for the Medium/Middle code model: 64-bit addresses, programs must be linked in the low 44 bits of memory, the text and data segments must be less than 2GB in size and the data segment must be located within 2GB of the text segment. `-mcmodel=medany' Generate code for the Medium/Anywhere code model: 64-bit addresses, programs may be linked anywhere in memory, the text and data segments must be less than 2GB in size and the data segment must be located within 2GB of the text segment. `-mcmodel=embmedany' Generate code for the Medium/Anywhere code model for embedded systems: 64-bit addresses, the text and data segments must be less than 2GB in size, both starting anywhere in memory (determined at link time). The global register %g4 points to the base of the data segment. Programs are statically linked and PIC is not supported. `-mstack-bias' `-mno-stack-bias' With `-mstack-bias', GCC assumes that the stack pointer, and frame pointer if present, are offset by -2047 which must be added back when making stack frame references. This is the default in 64-bit mode. Otherwise, assume no such offset is present. These switches are supported in addition to the above on Solaris: `-threads' Add support for multithreading using the Solaris threads library. This option sets flags for both the preprocessor and linker. This option does not affect the thread safety of object code produced by the compiler or that of libraries supplied with it. `-pthreads' Add support for multithreading using the POSIX threads library. This option sets flags for both the preprocessor and linker. This option does not affect the thread safety of object code produced by the compiler or that of libraries supplied with it. `-pthread' This is a synonym for `-pthreads'.  File: gcc.info, Node: SPU Options, Next: System V Options, Prev: SPARC Options, Up: Submodel Options 3.17.32 SPU Options ------------------- These `-m' options are supported on the SPU: `-mwarn-reloc' `-merror-reloc' The loader for SPU does not handle dynamic relocations. By default, GCC will give an error when it generates code that requires a dynamic relocation. `-mno-error-reloc' disables the error, `-mwarn-reloc' will generate a warning instead. `-msafe-dma' `-munsafe-dma' Instructions which initiate or test completion of DMA must not be reordered with respect to loads and stores of the memory which is being accessed. Users typically address this problem using the volatile keyword, but that can lead to inefficient code in places where the memory is known to not change. Rather than mark the memory as volatile we treat the DMA instructions as potentially effecting all memory. With `-munsafe-dma' users must use the volatile keyword to protect memory accesses. `-mbranch-hints' By default, GCC will generate a branch hint instruction to avoid pipeline stalls for always taken or probably taken branches. A hint will not be generated closer than 8 instructions away from its branch. There is little reason to disable them, except for debugging purposes, or to make an object a little bit smaller. `-msmall-mem' `-mlarge-mem' By default, GCC generates code assuming that addresses are never larger than 18 bits. With `-mlarge-mem' code is generated that assumes a full 32 bit address. `-mstdmain' By default, GCC links against startup code that assumes the SPU-style main function interface (which has an unconventional parameter list). With `-mstdmain', GCC will link your program against startup code that assumes a C99-style interface to `main', including a local copy of `argv' strings. `-mfixed-range=REGISTER-RANGE' Generate code treating the given register range as fixed registers. A fixed register is one that the register allocator can not use. This is useful when compiling kernel code. A register range is specified as two registers separated by a dash. Multiple register ranges can be specified separated by a comma. `-mdual-nops' `-mdual-nops=N' By default, GCC will insert nops to increase dual issue when it expects it to increase performance. N can be a value from 0 to 10. A smaller N will insert fewer nops. 10 is the default, 0 is the same as `-mno-dual-nops'. Disabled with `-Os'. `-mhint-max-nops=N' Maximum number of nops to insert for a branch hint. A branch hint must be at least 8 instructions away from the branch it is effecting. GCC will insert up to N nops to enforce this, otherwise it will not generate the branch hint. `-mhint-max-distance=N' The encoding of the branch hint instruction limits the hint to be within 256 instructions of the branch it is effecting. By default, GCC makes sure it is within 125. `-msafe-hints' Work around a hardware bug which causes the SPU to stall indefinitely. By default, GCC will insert the `hbrp' instruction to make sure this stall won't happen.  File: gcc.info, Node: System V Options, Next: V850 Options, Prev: SPU Options, Up: Submodel Options 3.17.33 Options for System V ---------------------------- These additional options are available on System V Release 4 for compatibility with other compilers on those systems: `-G' Create a shared object. It is recommended that `-symbolic' or `-shared' be used instead. `-Qy' Identify the versions of each tool used by the compiler, in a `.ident' assembler directive in the output. `-Qn' Refrain from adding `.ident' directives to the output file (this is the default). `-YP,DIRS' Search the directories DIRS, and no others, for libraries specified with `-l'. `-Ym,DIR' Look in the directory DIR to find the M4 preprocessor. The assembler uses this option.  File: gcc.info, Node: V850 Options, Next: VAX Options, Prev: System V Options, Up: Submodel Options 3.17.34 V850 Options -------------------- These `-m' options are defined for V850 implementations: `-mlong-calls' `-mno-long-calls' Treat all calls as being far away (near). If calls are assumed to be far away, the compiler will always load the functions address up into a register, and call indirect through the pointer. `-mno-ep' `-mep' Do not optimize (do optimize) basic blocks that use the same index pointer 4 or more times to copy pointer into the `ep' register, and use the shorter `sld' and `sst' instructions. The `-mep' option is on by default if you optimize. `-mno-prolog-function' `-mprolog-function' Do not use (do use) external functions to save and restore registers at the prologue and epilogue of a function. The external functions are slower, but use less code space if more than one function saves the same number of registers. The `-mprolog-function' option is on by default if you optimize. `-mspace' Try to make the code as small as possible. At present, this just turns on the `-mep' and `-mprolog-function' options. `-mtda=N' Put static or global variables whose size is N bytes or less into the tiny data area that register `ep' points to. The tiny data area can hold up to 256 bytes in total (128 bytes for byte references). `-msda=N' Put static or global variables whose size is N bytes or less into the small data area that register `gp' points to. The small data area can hold up to 64 kilobytes. `-mzda=N' Put static or global variables whose size is N bytes or less into the first 32 kilobytes of memory. `-mv850' Specify that the target processor is the V850. `-mbig-switch' Generate code suitable for big switch tables. Use this option only if the assembler/linker complain about out of range branches within a switch table. `-mapp-regs' This option will cause r2 and r5 to be used in the code generated by the compiler. This setting is the default. `-mno-app-regs' This option will cause r2 and r5 to be treated as fixed registers. `-mv850e1' Specify that the target processor is the V850E1. The preprocessor constants `__v850e1__' and `__v850e__' will be defined if this option is used. `-mv850e' Specify that the target processor is the V850E. The preprocessor constant `__v850e__' will be defined if this option is used. If neither `-mv850' nor `-mv850e' nor `-mv850e1' are defined then a default target processor will be chosen and the relevant `__v850*__' preprocessor constant will be defined. The preprocessor constants `__v850' and `__v851__' are always defined, regardless of which processor variant is the target. `-mdisable-callt' This option will suppress generation of the CALLT instruction for the v850e and v850e1 flavors of the v850 architecture. The default is `-mno-disable-callt' which allows the CALLT instruction to be used.  File: gcc.info, Node: VAX Options, Next: VxWorks Options, Prev: V850 Options, Up: Submodel Options 3.17.35 VAX Options ------------------- These `-m' options are defined for the VAX: `-munix' Do not output certain jump instructions (`aobleq' and so on) that the Unix assembler for the VAX cannot handle across long ranges. `-mgnu' Do output those jump instructions, on the assumption that you will assemble with the GNU assembler. `-mg' Output code for g-format floating point numbers instead of d-format.  File: gcc.info, Node: VxWorks Options, Next: x86-64 Options, Prev: VAX Options, Up: Submodel Options 3.17.36 VxWorks Options ----------------------- The options in this section are defined for all VxWorks targets. Options specific to the target hardware are listed with the other options for that target. `-mrtp' GCC can generate code for both VxWorks kernels and real time processes (RTPs). This option switches from the former to the latter. It also defines the preprocessor macro `__RTP__'. `-non-static' Link an RTP executable against shared libraries rather than static libraries. The options `-static' and `-shared' can also be used for RTPs (*note Link Options::); `-static' is the default. `-Bstatic' `-Bdynamic' These options are passed down to the linker. They are defined for compatibility with Diab. `-Xbind-lazy' Enable lazy binding of function calls. This option is equivalent to `-Wl,-z,now' and is defined for compatibility with Diab. `-Xbind-now' Disable lazy binding of function calls. This option is the default and is defined for compatibility with Diab.  File: gcc.info, Node: x86-64 Options, Next: Xstormy16 Options, Prev: VxWorks Options, Up: Submodel Options 3.17.37 x86-64 Options ---------------------- These are listed under *Note i386 and x86-64 Options::.  File: gcc.info, Node: Xstormy16 Options, Next: Xtensa Options, Prev: x86-64 Options, Up: Submodel Options 3.17.38 Xstormy16 Options ------------------------- These options are defined for Xstormy16: `-msim' Choose startup files and linker script suitable for the simulator.  File: gcc.info, Node: Xtensa Options, Next: zSeries Options, Prev: Xstormy16 Options, Up: Submodel Options 3.17.39 Xtensa Options ---------------------- These options are supported for Xtensa targets: `-mconst16' `-mno-const16' Enable or disable use of `CONST16' instructions for loading constant values. The `CONST16' instruction is currently not a standard option from Tensilica. When enabled, `CONST16' instructions are always used in place of the standard `L32R' instructions. The use of `CONST16' is enabled by default only if the `L32R' instruction is not available. `-mfused-madd' `-mno-fused-madd' Enable or disable use of fused multiply/add and multiply/subtract instructions in the floating-point option. This has no effect if the floating-point option is not also enabled. Disabling fused multiply/add and multiply/subtract instructions forces the compiler to use separate instructions for the multiply and add/subtract operations. This may be desirable in some cases where strict IEEE 754-compliant results are required: the fused multiply add/subtract instructions do not round the intermediate result, thereby producing results with _more_ bits of precision than specified by the IEEE standard. Disabling fused multiply add/subtract instructions also ensures that the program output is not sensitive to the compiler's ability to combine multiply and add/subtract operations. `-mtext-section-literals' `-mno-text-section-literals' Control the treatment of literal pools. The default is `-mno-text-section-literals', which places literals in a separate section in the output file. This allows the literal pool to be placed in a data RAM/ROM, and it also allows the linker to combine literal pools from separate object files to remove redundant literals and improve code size. With `-mtext-section-literals', the literals are interspersed in the text section in order to keep them as close as possible to their references. This may be necessary for large assembly files. `-mtarget-align' `-mno-target-align' When this option is enabled, GCC instructs the assembler to automatically align instructions to reduce branch penalties at the expense of some code density. The assembler attempts to widen density instructions to align branch targets and the instructions following call instructions. If there are not enough preceding safe density instructions to align a target, no widening will be performed. The default is `-mtarget-align'. These options do not affect the treatment of auto-aligned instructions like `LOOP', which the assembler will always align, either by widening density instructions or by inserting no-op instructions. `-mlongcalls' `-mno-longcalls' When this option is enabled, GCC instructs the assembler to translate direct calls to indirect calls unless it can determine that the target of a direct call is in the range allowed by the call instruction. This translation typically occurs for calls to functions in other source files. Specifically, the assembler translates a direct `CALL' instruction into an `L32R' followed by a `CALLX' instruction. The default is `-mno-longcalls'. This option should be used in programs where the call target can potentially be out of range. This option is implemented in the assembler, not the compiler, so the assembly code generated by GCC will still show direct call instructions--look at the disassembled object code to see the actual instructions. Note that the assembler will use an indirect call for every cross-file call, not just those that really will be out of range.  File: gcc.info, Node: zSeries Options, Prev: Xtensa Options, Up: Submodel Options 3.17.40 zSeries Options ----------------------- These are listed under *Note S/390 and zSeries Options::.  File: gcc.info, Node: Code Gen Options, Next: Environment Variables, Prev: Submodel Options, Up: Invoking GCC 3.18 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. `-fbounds-check' For front-ends that support it, generate additional code to check that indices used to access arrays are within the declared range. This is currently only supported by the Java and Fortran front-ends, where this option defaults to true and false respectively. `-ftrapv' This option generates traps for signed overflow on addition, subtraction, multiplication operations. `-fwrapv' This option instructs the compiler to assume that signed arithmetic overflow of addition, subtraction and multiplication wraps around using twos-complement representation. This flag enables some optimizations and disables others. This option is enabled by default for the Java front-end, as required by the Java language specification. `-fexceptions' Enable exception handling. Generates extra code needed to propagate exceptions. For some targets, this implies GCC 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, GCC 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. `-fnon-call-exceptions' Generate code that allows trapping instructions to throw exceptions. Note that this requires platform-specific runtime support that does not exist everywhere. Moreover, it only allows _trapping_ instructions to throw exceptions, i.e. memory references or floating point instructions. It does not allow exceptions to be thrown from arbitrary signal handlers such as `SIGALRM'. `-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. `-fasynchronous-unwind-tables' Generate unwind table in dwarf2 format, if supported by target machine. The table is exact at each instruction boundary, so it can be used for stack unwinding from asynchronous events (such as debugger or garbage collector). `-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, particularly the Portable C Compiler (pcc). 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. *Warning:* code compiled with the `-fpcc-struct-return' switch is not binary compatible with code compiled with the `-freg-struct-return' switch. Use it to conform to a non-default application binary interface. `-freg-struct-return' Return `struct' and `union' values in registers when possible. This is more efficient for small structures than `-fpcc-struct-return'. If you specify neither `-fpcc-struct-return' nor `-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. *Warning:* code compiled with the `-freg-struct-return' switch is not binary compatible with code compiled with the `-fpcc-struct-return' switch. Use it to conform to a non-default application binary interface. `-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. *Warning:* the `-fshort-enums' switch causes GCC to generate code that is not binary compatible with code generated without that switch. Use it to conform to a non-default application binary interface. `-fshort-double' Use the same size for `double' as for `float'. *Warning:* the `-fshort-double' switch causes GCC to generate code that is not binary compatible with code generated without that switch. Use it to conform to a non-default application binary interface. `-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. *Warning:* the `-fshort-wchar' switch causes GCC to generate code that is not binary compatible with code generated without that switch. Use it to conform to a non-default application binary interface. `-fno-common' In C, 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. The only reason this might be useful is if you wish to verify that the program will work on other systems which always work this way. `-fno-ident' Ignore the `#ident' directive. `-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. `-frecord-gcc-switches' This switch causes the command line that was used to invoke the compiler to be recorded into the object file that is being created. This switch is only implemented on some targets and the exact format of the recording is target and binary file format dependent, but it usually takes the form of a section containing ASCII text. This switch is related to the `-fverbose-asm' switch, but that switch only records information in the assembler output file as comments, so it never reaches the object file. `-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 8k on the SPARC and 32k on the m68k and RS/6000. The 386 has no such limit.) Position-independent code requires special support, and therefore works only on certain machines. For the 386, GCC supports PIC for System V but not for the Sun 386i. Code generated for the IBM RS/6000 is always position-independent. When this flag is set, the macros `__pic__' and `__PIC__' are defined to 1. `-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, PowerPC and SPARC. Position-independent code requires special support, and therefore works only on certain machines. When this flag is set, the macros `__pic__' and `__PIC__' are defined to 2. `-fpie' `-fPIE' These options are similar to `-fpic' and `-fPIC', but generated position independent code can be only linked into executables. Usually these options are used when `-pie' GCC option will be used during linking. `-fpie' and `-fPIE' both define the macros `__pie__' and `__PIE__'. The macros have the value 1 for `-fpie' and 2 for `-fPIE'. `-fno-jump-tables' Do not use jump tables for switch statements even where it would be more efficient than other code generation strategies. This option is of use in conjunction with `-fpic' or `-fPIC' for building code which forms part of a dynamic linker and cannot reference the address of a jump table. On some targets, jump tables do not require a GOT and this option is not needed. `-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 and are defined in the `REGISTER_NAMES' macro in the machine description macro file. 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[=N]' Without a value specified, pack all structure members together without holes. When a value is specified (which must be a small power of two), pack structure members according to this value, representing the maximum alignment (that is, objects with default alignment requirements larger than this will be output potentially unaligned at the next fitting location. *Warning:* the `-fpack-struct' switch causes GCC to generate code that is not binary compatible with code generated without that switch. Additionally, it makes the code suboptimal. Use it to conform to a non-default application binary interface. `-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). `-finstrument-functions-exclude-file-list=FILE,FILE,...' Set the list of functions that are excluded from instrumentation (see the description of `-finstrument-functions'). If the file that contains a function definition matches with one of FILE, then that function is not instrumented. The match is done on substrings: if the FILE parameter is a substring of the file name, it is considered to be a match. For example, `-finstrument-functions-exclude-file-list=/bits/stl,include/sys' will exclude any inline function defined in files whose pathnames contain `/bits/stl' or `include/sys'. If, for some reason, you want to include letter `','' in one of SYM, write `'\,''. For example, `-finstrument-functions-exclude-file-list='\,\,tmp'' (note the single quote surrounding the option). `-finstrument-functions-exclude-function-list=SYM,SYM,...' This is similar to `-finstrument-functions-exclude-file-list', but this option sets the list of function names to be excluded from instrumentation. The function name to be matched is its user-visible name, such as `vector blah(const vector &)', not the internal mangled name (e.g., `_Z4blahRSt6vectorIiSaIiEE'). The match is done on substrings: if the SYM parameter is a substring of the function name, it is considered to be a match. `-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 absolute address `0x80000000' and grows downwards, you can use the flags `-fstack-limit-symbol=__stack_limit' and `-Wl,--defsym,__stack_limit=0x7ffe0000' to enforce a stack limit of 128KB. Note that this may only work with the GNU linker. `-fargument-alias' `-fargument-noalias' `-fargument-noalias-global' `-fargument-noalias-anything' 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. `-fargument-noalias-anything' specifies that arguments do not alias any other 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. *Warning:* the `-fleading-underscore' switch causes GCC to generate code that is not binary compatible with code generated without that switch. Use it to conform to a non-default application binary interface. Not all targets provide complete support for this switch. `-ftls-model=MODEL' Alter the thread-local storage model to be used (*note Thread-Local::). The MODEL argument should be one of `global-dynamic', `local-dynamic', `initial-exec' or `local-exec'. The default without `-fpic' is `initial-exec'; with `-fpic' the default is `global-dynamic'. `-fvisibility=DEFAULT|INTERNAL|HIDDEN|PROTECTED' Set the default ELF image symbol visibility to the specified option--all symbols will be marked with this unless overridden within the code. Using this feature can very substantially improve linking and load times of shared object libraries, produce more optimized code, provide near-perfect API export and prevent symbol clashes. It is *strongly* recommended that you use this in any shared objects you distribute. Despite the nomenclature, `default' always means public ie; available to be linked against from outside the shared object. `protected' and `internal' are pretty useless in real-world usage so the only other commonly used option will be `hidden'. The default if `-fvisibility' isn't specified is `default', i.e., make every symbol public--this causes the same behavior as previous versions of GCC. A good explanation of the benefits offered by ensuring ELF symbols have the correct visibility is given by "How To Write Shared Libraries" by Ulrich Drepper (which can be found at `http://people.redhat.com/~drepper/')--however a superior solution made possible by this option to marking things hidden when the default is public is to make the default hidden and mark things public. This is the norm with DLL's on Windows and with `-fvisibility=hidden' and `__attribute__ ((visibility("default")))' instead of `__declspec(dllexport)' you get almost identical semantics with identical syntax. This is a great boon to those working with cross-platform projects. For those adding visibility support to existing code, you may find `#pragma GCC visibility' of use. This works by you enclosing the declarations you wish to set visibility for with (for example) `#pragma GCC visibility push(hidden)' and `#pragma GCC visibility pop'. Bear in mind that symbol visibility should be viewed *as part of the API interface contract* and thus all new code should always specify visibility when it is not the default ie; declarations only for use within the local DSO should *always* be marked explicitly as hidden as so to avoid PLT indirection overheads--making this abundantly clear also aids readability and self-documentation of the code. Note that due to ISO C++ specification requirements, operator new and operator delete must always be of default visibility. Be aware that headers from outside your project, in particular system headers and headers from any other library you use, may not be expecting to be compiled with visibility other than the default. You may need to explicitly say `#pragma GCC visibility push(default)' before including any such headers. `extern' declarations are not affected by `-fvisibility', so a lot of code can be recompiled with `-fvisibility=hidden' with no modifications. However, this means that calls to `extern' functions with no explicit visibility will use the PLT, so it is more effective to use `__attribute ((visibility))' and/or `#pragma GCC visibility' to tell the compiler which `extern' declarations should be treated as hidden. Note that `-fvisibility' does affect C++ vague linkage entities. This means that, for instance, an exception class that will be thrown between DSOs must be explicitly marked with default visibility so that the `type_info' nodes will be unified between the DSOs. An overview of these techniques, their benefits and how to use them is at `http://gcc.gnu.org/wiki/Visibility'.  File: gcc.info, Node: Environment Variables, Next: Precompiled Headers, Prev: Code Gen Options, Up: Invoking GCC 3.19 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' (*note Directory Options::). These take precedence over places specified using environment variables, which in turn take precedence over those specified by the configuration of GCC. *Note Controlling the Compilation Driver `gcc': (gccint)Driver. `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_GB.UTF-8' for English in the United Kingdom encoded in UTF-8. 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, GCC 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/' where PREFIX is the prefix to the installed compiler. In many cases 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' (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. If a standard directory begins with the configured PREFIX then the value of PREFIX is replaced by `GCC_EXEC_PREFIX' when looking for header files. `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). `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. Some additional environments variables affect the behavior of the preprocessor. `CPATH' `C_INCLUDE_PATH' `CPLUS_INCLUDE_PATH' `OBJC_INCLUDE_PATH' Each variable's value is a list of directories separated by a special character, much like `PATH', in which to look for header files. The special character, `PATH_SEPARATOR', is target-dependent and determined at GCC build time. For Microsoft Windows-based targets it is a semicolon, and for almost all other targets it is a colon. `CPATH' specifies a list of directories to be searched as if specified with `-I', but after any paths given with `-I' options on the command line. This environment variable is used regardless of which language is being preprocessed. The remaining environment variables apply only when preprocessing the particular language indicated. Each specifies a list of directories to be searched as if specified with `-isystem', but after any paths given with `-isystem' options on the command line. In all these variables, an empty element instructs the compiler to search its current working directory. Empty elements can appear at the beginning or end of a path. For instance, if the value of `CPATH' is `:/special/include', that has the same effect as `-I. -I/special/include'. `DEPENDENCIES_OUTPUT' If this variable is set, its value specifies how to output dependencies for Make based on the non-system header files processed by the compiler. System header files are ignored in the dependency output. 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. In other words, this environment variable is equivalent to combining the options `-MM' and `-MF' (*note Preprocessor Options::), with an optional `-MT' switch too. `SUNPRO_DEPENDENCIES' This variable is the same as `DEPENDENCIES_OUTPUT' (see above), except that system header files are not ignored, so it implies `-M' rather than `-MM'. However, the dependence on the main input file is omitted. *Note Preprocessor Options::.  File: gcc.info, Node: Precompiled Headers, Next: Running Protoize, Prev: Environment Variables, Up: Invoking GCC 3.20 Using Precompiled Headers ============================== Often large projects have many header files that are included in every source file. The time the compiler takes to process these header files over and over again can account for nearly all of the time required to build the project. To make builds faster, GCC allows users to `precompile' a header file; then, if builds can use the precompiled header file they will be much faster. To create a precompiled header file, simply compile it as you would any other file, if necessary using the `-x' option to make the driver treat it as a C or C++ header file. You will probably want to use a tool like `make' to keep the precompiled header up-to-date when the headers it contains change. A precompiled header file will be searched for when `#include' is seen in the compilation. As it searches for the included file (*note Search Path: (cpp)Search Path.) the compiler looks for a precompiled header in each directory just before it looks for the include file in that directory. The name searched for is the name specified in the `#include' with `.gch' appended. If the precompiled header file can't be used, it is ignored. For instance, if you have `#include "all.h"', and you have `all.h.gch' in the same directory as `all.h', then the precompiled header file will be used if possible, and the original header will be used otherwise. Alternatively, you might decide to put the precompiled header file in a directory and use `-I' to ensure that directory is searched before (or instead of) the directory containing the original header. Then, if you want to check that the precompiled header file is always used, you can put a file of the same name as the original header in this directory containing an `#error' command. This also works with `-include'. So yet another way to use precompiled headers, good for projects not designed with precompiled header files in mind, is to simply take most of the header files used by a project, include them from another header file, precompile that header file, and `-include' the precompiled header. If the header files have guards against multiple inclusion, they will be skipped because they've already been included (in the precompiled header). If you need to precompile the same header file for different languages, targets, or compiler options, you can instead make a _directory_ named like `all.h.gch', and put each precompiled header in the directory, perhaps using `-o'. It doesn't matter what you call the files in the directory, every precompiled header in the directory will be considered. The first precompiled header encountered in the directory that is valid for this compilation will be used; they're searched in no particular order. There are many other possibilities, limited only by your imagination, good sense, and the constraints of your build system. A precompiled header file can be used only when these conditions apply: * Only one precompiled header can be used in a particular compilation. * A precompiled header can't be used once the first C token is seen. You can have preprocessor directives before a precompiled header; you can even include a precompiled header from inside another header, so long as there are no C tokens before the `#include'. * The precompiled header file must be produced for the same language as the current compilation. You can't use a C precompiled header for a C++ compilation. * The precompiled header file must have been produced by the same compiler binary as the current compilation is using. * Any macros defined before the precompiled header is included must either be defined in the same way as when the precompiled header was generated, or must not affect the precompiled header, which usually means that they don't appear in the precompiled header at all. The `-D' option is one way to define a macro before a precompiled header is included; using a `#define' can also do it. There are also some options that define macros implicitly, like `-O' and `-Wdeprecated'; the same rule applies to macros defined this way. * If debugging information is output when using the precompiled header, using `-g' or similar, the same kind of debugging information must have been output when building the precompiled header. However, a precompiled header built using `-g' can be used in a compilation when no debugging information is being output. * The same `-m' options must generally be used when building and using the precompiled header. *Note Submodel Options::, for any cases where this rule is relaxed. * Each of the following options must be the same when building and using the precompiled header: -fexceptions -funit-at-a-time * Some other command-line options starting with `-f', `-p', or `-O' must be defined in the same way as when the precompiled header was generated. At present, it's not clear which options are safe to change and which are not; the safest choice is to use exactly the same options when generating and using the precompiled header. The following are known to be safe: -fmessage-length= -fpreprocessed -fsched-interblock -fsched-spec -fsched-spec-load -fsched-spec-load-dangerous -fsched-verbose= -fschedule-insns -fvisibility= -pedantic-errors For all of these except the last, the compiler will automatically ignore the precompiled header if the conditions aren't met. If you find an option combination that doesn't work and doesn't cause the precompiled header to be ignored, please consider filing a bug report, see *note Bugs::. If you do use differing options when generating and using the precompiled header, the actual behavior will be a mixture of the behavior for the options. For instance, if you use `-g' to generate the precompiled header but not when using it, you may or may not get debugging information for routines in the precompiled header.  File: gcc.info, Node: Running Protoize, Prev: Precompiled Headers, Up: Invoking GCC 3.21 Running Protoize ===================== The program `protoize' is an optional part of GCC. You can use it to add prototypes to a program, thus converting the program to ISO 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