Sun Studio 12 Update 1: C++ User's Guide

Chapter 3 Using the C++ Compiler Options

This chapter explains how to use the command-line C++ compiler options and then summarizes their use by function. Detailed explanations of the options are provided in A.2 Option Reference.

3.1 Syntax

The following table shows examples of typical option syntax formats that are used in this book.

Table 3–1 Option Syntax Format Examples


Syntax Format	Example
`-option`	`–E`
`–optionvalue`	`–Ipathname`
`–option=value`	`–xunroll=4`
`–option` `value`	`–o` `filename`

Parentheses, braces, brackets, pipe characters, and ellipses are metacharacters used in the descriptions of the options and are not part of the options themselves. See the typographical conventions in the Preface to this manual for a detailed explanation of the usage syntax.

3.2 General Guidelines

Some general guidelines for the C++ compiler options are:

The– llib option links with library liblib.a (or liblib.so). It is always safer to put– llib after the source and object files to ensure the order in which libraries are searched.
In general, processing of the compiler options is from left to right (with the exception that– U options are processed after all– D options), allowing selective overriding of macro options (options that include other options). This rule does not apply to linker options.
The -features,–I -l, –L, -library, –pti, –R, -staticlib, -U, -verbose, and -xprefetch options accumulate, they do not override.
The -D option accumulates, However, multiple -D options for the same name override each other.

Source files, object files, and libraries are compiled and linked in the order in which they appear on the command line.

3.3 Options Summarized by Function

In this section, the compiler options are grouped by function to provide a quick reference. For a detailed description of each option, refer to Appendix A, C++ Compiler Options.

The options apply to all platforms except as noted; features that are unique to the Solaris OS on SPARC-based systems are identified as SPARC, and the features that are unique to the Solaris OS on x86-based systems are identified as x86.

3.3.1 Code Generation Options

Table 3–2 Code Generation Options


Option	Action
`–compat`	Sets the major release compatibility mode of the compiler.
`+e{0\|1}`	Controls virtual table generation.
`–g`	Compiles for use with the debugger.
`–KPIC`	Produces position-independent code.
`–Kpic`	Produces position-independent code.
`–mt`	Compiles and links for multithreaded code.
`-xaddr32`	Restrict code to 32–bit address space (x86/x64)
`-xarch`	Specify target architecture.
`–xcode=a`	(SPARC) Specifies the code address space.
`–xMerge`	(SPARC) Merges the data segment with the text segment.
`-xtarget`	Specify target system.
`–xmodel`	Modifies the form of 64-bit objects for the Solaris x86 platforms
`+w`	Identifies code that might have unintended consequences.
`+w2`	Emits all the warnings emitted by `+w` plus warnings about technical violations that are probably harmless, but that might reduce the maximum portability of your program.
`-xregs`	The compiler can generate faster code if it has more registers available for temporary storage (scratch registers). This option makes available additional scratch registers that might not always be appropriate.
`-z` `arg`	Linker option.

3.3.2 Compile-Time Performance Options

Table 3–3 Compile-Time Performance Options


Option	Action
`–instlib`	Inhibits the generation of template instances that are already present in the designated library.
`-m32`\|`-m64`	Specifies the memory model for the compiled binary object.
`-xinstrument`	Compiles and instruments your program for analysis by the Thread Analyzer.
`–xjobs`	Sets the number of processes the compiler can create to complete its work.
`–xpch`	May reduce compile time for applications whose source files share a common set of include files.
`–xpchstop`	Specifies the last include file to be considered in creating a pre-compiled header file with `-xpch`.
`–xprofile_ircache`	(SPARC) Reuses compilation data saved during `-xprofile=collect`.
`–xprofile_pathmap`	(SPARC) Support for multiple programs or shared libraries in a single profile directory.

3.3.3 Compile-Time and Link-Time Options

The following table lists the options that must be specified both at link-time and at compile-time.

Table 3–4 Compile-Time and Link-Time Options


Option	Action
`-fast`	Selects the optimum combination of compilation options for speed of executable code.
`-m32`\|`-m64`	Specifies the memory model for the compiled binary object.
`-mt`	Macro option that expands to `-D_REENTRANT` `-lthread`.
`-xarch`	Specify instruction set architecture.
`-xautopar`	Turns on automatic parallelization for multiple processors.
`-xhwcprof`	(SPARC) Enables compiler support for hardware counter-based profiling.
`-xipo`	Performs whole-program optimizations by invoking an interprocedural analysis component.
`-xlinkopt`	Performs link-time optimizations on relocatable object files.
`-xmemalign`	(SPARC) Specify maximum assumed memory alignment and behavior of misaligned data accesses.
`-xopenmp`	Supports the OpenMP interface for explicit parallelization including a set of source code directives, run-time library routines, and environment variables
`-xpagesize`	Sets the preferred page size for the stack and the heap.
`-xpagesize_heap`	Sets the preferred page size for the heap.
`-xpagesize_stack`	Sets the preferred page size for the stack.
`-xpg`	Prepares the object code to collect data for profiling with `gprof`(1).
`-xprofile`	Collects data for a profile or uses a profile to optimize.
`-xvector`	Enable automatic generation of calls to the vector library functions.

3.3.4 Debugging Options

Table 3–5 Debugging Options


Option	Action
`+d`	Does not expand C++ inline functions.
`–dryrun`	Shows options passed by the driver to the compiler, but does not compile.
`–E`	Runs only the preprocessor on the C++ source files and sends result to `stdout`. Does not compile.
`–g`	Compiles for use with the debugger.
`–g0`	Compiles for debugging, but doesn’t disable inlining.
`–H`	Prints path names of included files.
`–keeptmp`	Retains temporary files created during compilation.
`–migration`	Explains where to get information about migrating from earlier compilers.
`–P`	Only preprocesses source; outputs to `.i` file.
`–Qoption`	Passes an option directly to a compilation phase.
`–readme`	Displays the content of the online `README` file.
`–s`	Strips the symbol table out of the executable file, thus preventing the ability to debug code.
`–temp=dir`	Defines directory for temporary files.
`–verbose=vlst`	Controls compiler verbosity.
`-xcheck`	Adds a runtime check for stack overflow.
`-xdumpmacros`	Prints information about macros such as definition, location defined and undefined, and locations used.
`–xe`	Only checks for syntax and semantic errors.
`–xhelp=flags`	Displays a summary list of compiler options.
`–xport64`	Warns against common problems during a port from a 32-bit architecture to a 64-bit architecture.

3.3.5 Floating-Point Options

Table 3–6 Floating-Point Options


Option	Action
`-fma`	(SPARC) Enables automatic generation of floating-point, fused, multiply-add instructions.
`–fns[={no\|yes`}]	(SPARC) Disables or enables the SPARC nonstandard floating-point mode.
`–fprecision=p`	x86: Sets floating-point precision mode.
`–fround=r`	Sets IEEE rounding mode in effect at startup.
`–fsimple=n`	Sets floating-point optimization preferences.
`–fstore`	x86: Forces precision of floating-point expressions.
`–ftrap=tlst`	Sets IEEE trapping mode in effect at startup.
`–nofstore`	x86: Disables forced precision of expression.
`–xlibmieee`	Causes `libm` to return IEEE 754 values for math routines in exceptional cases.

3.3.6 Language Options

Table 3–7 Language Options


Option	Action
`–compat`	Sets the major release compatibility mode of the compiler.
`–features=alst`	Enables or disables various C++ language features.
`-xchar`	Eases the migration of code from systems where the char type is defined as unsigned.
`–xldscope`	Controls the default linker scope of variable and function definitions to create faster and safer shared libraries.
`–xthreadvar`	(SPARC) Changes the default thread-local storage access mode.
`-xtrigraphs`	Enables recognition of trigraph sequences.
`–xustr`	Enables recognition of string literals composed of sixteen-bit characters.

3.3.7 Library Options

Table 3–8 Library Options


Option	Action
`–Bbinding`	Requests symbolic, dynamic, or static library linking.
`–d{y\|n}`	Allows or disallows dynamic libraries for the entire executable.
`–G`	Builds a dynamic shared library instead of an executable file.
`–hname`	Assigns an internal name to the generated dynamic shared library.
`–i`	Tells `ld`(1) to ignore any `LD_LIBRARY_PATH` setting.
`–Ldir`	Adds dir to the list of directories to be searched for libraries.
`–llib`	Adds `lib`lib`.a` or `lib`lib`.so` to the linker’s library search list.
`–library=llst`	Forces inclusion of specific libraries and associated files into compilation and linking.
`–mt`	Compiles and links for multithreaded code.
`–norunpath`	Does not build path for libraries into executable.
`–Rplst`	Builds dynamic library search paths into the executable file.
`–staticlib=llst`	Indicates which C++ libraries are to be linked statically.
`–xar`	Creates archive libraries.
`-xbuiltin`[`=opt`]	Enables or disables better optimization of standard library calls
`-xia`	(Solaris) Links the appropriate interval arithmetic libraries and sets a suitable floating-point environment.
`-xlang=l`[,`l`]	Includes the appropriate runtime libraries and ensures the proper runtime environment for the specified language.
`–xlibmieee`	Causes `libm` to return IEEE 754 values for math routines in exceptional cases.
`–xlibmil`	Inlines selected `libm` library routines for optimization.
`–xlibmopt`	Uses library of optimized math routines.
`–xnolib`	Disables linking with default system libraries.
`–xnolibmil`	Cancels`– xlibmil` on the command line.
`–xnolibmopt`	Does not use the math routine library.

3.3.8 Obsolete Options

Note –

The following options are either currently obsolete and so no longer accepted by the compiler, or they will be removed in a future release.

Table 3–9 Obsolete Options


Option	Action
`-library=%all`	Obsolete option that will be removed in a future release.
`-xlic_lib=sunperf`	Use `—library=sunperf` to link to the Sun Performance Library.
`-xlicinfo`	Deprecated.
`–noqueue`	Disables license queueing.
`-ptr`	Ignored by the compiler. A future release of the compiler may reuse this option using a different behavior.
`-sb, —sbfast, —xsb, —xsbfast`	Deprecated and silently ignored.
`-vdelx`	Obsolete option that will be removed in a future release.
`-x386`	Use an appropriate `—xtarget` option.
`-x486`	Use an appropriate `—xtarget` option.
`-xcg89`	Use `-xtarget=ss2`
`-xcrossfile`	Use `-xipo` instead.
`-xnativeconnect`	Obsolete, there is no alternative option.
`-xprefetch=yes`	Use `-xprefetch=auto,explicit` instead.
`-xprefetch=no`	Use `-xprefetch=no%auto,no%explicit` instead.
`-xvector=yes`	Use `-xvector=lib` instead.
`-xvector=no`	Use `-xvecttor=none` instead.

3.3.9 Output Options

Table 3–10 Output Options


Option	Action
`–c`	Compiles only; produces object (`.o`) files, but suppresses linking.
`–dryrun`	Shows all the command lines issued by the driver to the compiler, but does not compile.
`–E`	Runs only the preprocessor on the C++ source files and sends result to `stdout`. Does not compile.
`-erroff`	Suppresses compiler warning messages.
`-errtags`	Displays the message tag for each warning message.
`-errwarn`	If the indicated warning message is issued, cc exits with a failure status.
`-filt`	Suppresses the filtering that the compiler applies to linker error messages.
`–G`	Builds a dynamic shared library instead of an executable file.
`–H`	Prints path names of included files.
`–migration`	Explains where to get information about migrating from earlier compilers.
`–o` `filename`	Sets name of the output or executable file to `filename`.
`–P`	Only preprocesses source; outputs to `.i` file.
`–Qproduce` `sourcetype`	Causes the `CC` driver to produce output of the type `sourcetype`.
`–s`	Strips the symbol table out of the executable file.
`–verbose=vlst`	Controls compiler verbosity.
`+w`	Prints extra warnings where necessary.
`+w2`	Print still more warnings where appropriate.
`–w`	Suppresses warning messages.
`-xdumpmacros`	Prints information about macros such as definition, location defined and undefined, and locations used.
`-xe`	Performs only syntax and semantic checking on the source file, but does not produce any object or executable code.
`–xhelp=flags`	Displays a summary list of compiler options
`–xhelp=readme`	Displays the contents of the online `README` file.
`–xM`	Outputs makefile dependency information.
`–xM1`	Generates dependency information, but excludes `/usr/include`.
`–xtime`	Reports execution time for each compilation phase.
`–xwe`	Converts all warnings to errors.
`-z` `arg`	Linker option.

3.3.10 Run-Time Performance Options

Table 3–11 Run-Time Performance Options


Option	Action
`–fast`	Selects a combination of compilation options for optimum execution speed for some programs.
`-fma`	(SPARC) Enables automatic generation of floating-point, fused, multiply-add instructions.
`-g`	Instructs both the compiler and the linker to prepare the program for performance analysis (and for debugging).
`–s`	Strips the symbol table out of the executable.
`-m32`\|`-m64`	Specifies the memory model for the compiled binary object.
`-xalias_level`	Enables the compiler to perform type-based alias analysis and optimizations.
`–xarch=isa`	Specifies target architecture instruction set.
`-xbinopt`	Prepares the binary for later optimizations, transformations and analysis.
`-xbuiltin`[`=opt`]	Enables or disables better optimization of standard library calls
`–xcache=c`	(SPARC) Defines target cache properties for the optimizer.
`–xcg89`	Compiles for generic SPARC v7 architecture.
`–xcg92`	Compiles for SPARC V8 architecture.
`–xchip=c`	Specifies target processor chip.
`–xF`	Enables linker reordering of functions and variables.
`-xinline=flst`	Specifies which user-written routines can be inlined by the optimizer
`-xipo`	Performs interprocedural optimizations.
`–xlibmil`	Inlines selected `libm` library routines for optimization.
`–xlibmopt`	Uses a library of optimized math routines.
`–xlinkopt`	(SPARC) Performs link-time optimization on the resulting executable or dynamic library over and above any optimizations in the object files.
`–xmemalign=`ab	(SPARC) Specify maximum assumed memory alignment and behavior of misaligned data accesses.
`–xnolibmil`	Cancels`– xlibmil` on the command line.
`–xnolibmopt`	Does not use the math routine library.
`–xOlevel`	Specifies optimization level to level.
`–xpagesize`	Sets the preferred page size for the stack and the heap.
`-xpagesize_heap`	Sets the preferred page size for the heap.
`-xpagesize_stack`	Sets the preferred page size for the stack.
`-xprefetch`[`=lst`]	Enables prefetch instructions on architectures that support prefetch.
`-xprefetch_level`	Control the aggressiveness of automatic insertion of prefetch instructions as set by `-xprefetch=auto`
`–xprofile`	Collects or optimizes using runtime profiling data.
`–xregs=rlst`	Controls scratch register use.
`–xsafe=mem`	(SPARC) Allows no memory-based traps.
`–xspace`	(SPARC) Does not allow optimizations that increase code size.
`–xtarget=t`	Specifies a target instruction set and optimization system.
`–xthreadvar`	Changes the default thread-local storage access mode.
`–xunroll=n`	Enables unrolling of loops where possible.
`–xvis`	(SPARC) Enables compiler recognition of the assembly-language templates defined in the VIS^TM instruction set

3.3.11 Preprocessor Options

Table 3–12 Preprocessor Options


Option	Action
`–Dname[=def]`	Defines symbol `name` to the preprocessor.
`–E`	Runs only the preprocessor on the C++ source files and sends result to `stdout`. Does not compile.
`-H`	Prints path names of included files.
`–P`	Only preprocesses source; outputs to `.i` file.
`–Uname`	Deletes initial definition of preprocessor symbol `name`.
`–xM`	Outputs makefile dependency information.
`–xM1`	Generates dependency information, but excludes `/usr/include`.

3.3.12 Profiling Options

Table 3–13 Profiling Options


Option	Action
`–p`	Prepares the object code to collect data for profiling using `prof`.
`–xa`	Generates code for profiling.
`–xpg`	Compiles for profiling with the `gprof` profiler.
`–xprofile`	Collects or optimizes using runtime profiling data.

3.3.13 Reference Options

Table 3–14 Reference Options


Option	Action
`–migration`	Explains where to get information about migrating from earlier compilers.
`–xhelp=flags`	Displays a summary list of compiler options.
`–xhelp=readme`	Displays the contents of the online `README` file.

3.3.14 Source Options

Table 3–15 Source Options


Option	Action
`-H`	Prints path names of included files.
`–Ipathname`	Adds `pathname` to the `include` file search path.
`-I-`	Changes the include-file search rules
`–xM`	Outputs makefile dependency information.
`–xM1`	Generates dependency information, but excludes `/usr/include`.

3.3.15 Template Options

Table 3–16 Template Options


Option	Action
`–instances=a`	Controls the placement and linkage of template instances.
`–template=wlst`	Enables or disables various template options.

3.3.16 Thread Options

Table 3–17 Thread Options


Option	Action
`–mt`	Compiles and links for multithreaded code.
`–xsafe=mem`	(SPARC) Allows no memory-based traps.
`–xthreadvar`	(SPARC) Changes the default thread-local storage access mode.