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 Appendix A.
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 "Before You Begin" at the front of 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.
The options apply to all platforms except as noted; features that are unique to the Solaris SPARC Platform Edition operating environment are identified as SPARC, and the features that are unique to the Solaris Intel Platform Edition operating environment are identified as IA.
3.3.1 Code Generation Options
The following code generation options are listed in alphabetical order.
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.
|
-xcode=a
|
Specifies the code address space.
|
-xMerge
|
Merges the data segment with the text segment.
|
+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 Debugging Options
The following debugging options are listed in alphabetical order.
TABLE 3-3 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.
|
-xhelp=flags
|
Displays a summary list of compiler options.
|
-xildoff
|
Turns off the Incremental Linker.
|
-xildon
|
Turns on the Incremental Linker.
|
-xs
|
Allows debugging with dbx without object (.o) files.
|
-xsb
|
Produces table information for the source browser.
|
-xsbfast
|
Produces only source browser information, no compilation.
|
3.3.3 Floating-Point Options
The following floating-point options are listed in alphabetical order.
TABLE 3-4 Floating-Point Options
Option
|
Action
|
-fns[={no|yes}]
|
Disables or enables the SPARC nonstandard floating-point mode.
|
-fprecision=p
|
IA: Sets floating-point precision mode.
|
-fround=r
|
Sets IEEE rounding mode in effect at startup.
|
-fsimple=n
|
Sets floating-point optimization preferences.
|
-fstore
|
IA: Forces precision of floating-point expressions.
|
-ftrap=tlst
|
Sets IEEE trapping mode in effect at startup.
|
-nofstore
|
IA: Disables forced precision of expression.
|
-xlibmieee
|
Causes libm to return IEEE 754 values for math routines in exceptional cases.
|
3.3.4 Language Options
The following language options are listed in alphabetical order.
TABLE 3-5 Language Options
Option
|
Action
|
-compat
|
Sets the major release compatibility mode of the compiler.
|
-features=alst
|
Enables or disables various C++ language features.
|
-xtrigraphs
|
Enables recognition of trigraph sequences.
|
3.3.5 Library Options
The following library linking options are listed in alphabetical order.
TABLE 3-6 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 a 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 liblib.a or liblib.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
|
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.
|
-xlic_lib=sunperf
|
SPARC: Links in the Sun Performance Library . Note that for C++, -library=sunperf is the preferable method for linking in this library.
|
-xnativeconnect
|
Includes fsinterface information inside object files and subsequent shared libraries so that the shared library can interface with code written in the Java[tm] programming language.
|
-xnolib
|
Disables linking with default system libraries.
|
-xnolibmil
|
Cancels -xlibmil on the command line.
|
-xnolibmopt
|
Does not use the math routine library.
|
3.3.6 Licensing Options
The following licensing options are listed in alphabetical order.
TABLE 3-7 Licensing Options
Option
|
Action
|
-noqueue
|
Disables license queueing.
|
-xlic_lib=sunperf
|
SPARC: Links in the Sun Performance Library . Note that for C++, -library=sunperf is the preferable method for linking in this library.
|
-xlicinfo
|
Shows license server information.
|
3.3.7 Obsolete Options
The following options are obsolete or will become obsolete.
TABLE 3-8 Obsolete Options
Option
|
Action
|
-library=%all
|
Obsolete option that will be removed in a future release.
|
-ptr
|
Ignored by the compiler. A future release of the compiler may reuse this option using a different behavior.
|
-vdelx
|
Obsolete option that will be removed in a future release.
|
3.3.8 Output Options
The following output options are listed in alphabetical order.
TABLE 3-9 Output Options
Option
|
Action
|
-c
|
Compiles only; produces object (.o) files, but suppresses linking.
|
-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.
|
-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.
|
-w
|
Suppresses warning messages.
|
-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.
|
-xsb
|
Produces table information for the source browser.
|
-xsbfast
|
Produces only source browser information, no compilation.
|
-xtime
|
Reports execution time for each compilation phase.
|
-xwe
|
Converts all warnings to errors by returning non-zero exit status.
|
-z arg
|
Linker option.
|
3.3.9 Performance Options
The following performance options are listed in alphabetical order.
TABLE 3-10 Performance Options
Option
|
Action
|
-fast
|
Selects a combination of compilation options for optimum execution speed for some programs.
|
-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.
|
-xalias_level
|
Enables the compiler to perform type-based alias analysis and optimizations.
|
-xarch=isa
|
Specifies target architecture instruction set.
|
-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 architecture.
|
-xcg92
|
Compiles for SPARC V8 architecture.
|
-xchip=c
|
Specifies target processor chip.
|
-xF
|
Enables linker reordering of functions.
|
-xinline=flst
|
Specifies which user-written routines can be inlined by the optimizer
|
-xipo[={0|1}]
|
Performs interprocedural optimizations.
|
-xlibmil
|
Inlines selected libm library routines for optimization.
|
-xlibmopt
|
Uses a library of optimized math routines.
|
-xnolibmil
|
Cancels -xlibmil on the command line.
|
-xnolibmopt
|
Does not use the math routine library.
|
-xOlevel
|
Specifies optimization level to level.
|
-xprefetch[=lst]
|
SPARC: Enables prefetch instructions on architectures that support prefetch.
|
-xprefetch_level
|
Control the aggressiveness of automatic insertion of prefetch instructions as set by -xprefetch=auto
|
-xregs=rlst
|
SPARC: 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.
|
-xunroll=n
|
Enables unrolling of loops where possible.
|
3.3.10 Preprocessor Options
The following preprocessor options are listed in alphabetical order.
TABLE 3-11 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.11 Profiling Options
The following profiling options are listed in alphabetical order.
TABLE 3-12 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=tcov
|
Collects or optimizes using runtime profiling data.
|
3.3.12 Reference Options
The following options provide a quick reference to compiler information.
TABLE 3-13 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.13 Source Options
The following source options are listed in alphabetical order.
TABLE 3-14 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.14 Template Options
The following template options are listed in alphabetical order.
TABLE 3-15 Template Options
Option
|
Action
|
-instances=a
|
Controls the placement and linkage of template instances.
|
-ptipath
|
Specifies an additional search directory for the template source.
|
-template=wlst
|
Enables or disables various template options.
|
3.3.15 Thread Options
The following thread options are listed in alphabetical order.
TABLE 3-16 Thread Options
Option
|
Action
|
-mt
|
Compiles and links for multithreaded code.
|
-xsafe=mem
|
SPARC: Allows no memory-based traps.
|