| C++ User's Guide |    
|
| C++ User's Guide |
|
| A P P E N D I X A |
|
C++ Compiler Options |
This appendix details the command-line options for the CC compiler running under Solaris 7 and Solaris 8. The features described 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.
The following table shows examples of typical option syntax formats.
The typographical conventions that are listed in "Before You Begin" at the front of this manual are used in this section of the manual to describe individual options.
Parentheses, braces, brackets, pipe characters, and ellipses are metacharacters used in the descriptions of the options and are not part of the options themselves.
To help you find information, compiler option descriptions are separated into the following subsections. If the option is one that is replaced by or identical to some other option, see the description of the other option for full details.
IA: Same as -xtarget=386. This option is provided for backward compatibility only.
IA: Same as -xtarget=486. This option is provided for backward compatibility only.
Specifies whether a library binding for linking is symbolic, dynamic (shared), or static (nonshared).
You can use the -B option several times on a command line. This option is passed to the linker, ld.
|
Note - On the Solaris 7 and Solaris 8 platforms, not all libraries are available as static libraries. |
binding must be one of the following:
(No space is allowed between -B and the binding value.)
If -B is not specified, -Bdynamic is assumed.
To link the C++ default libraries statically, use the -staticlib option.
The -Bstatic and -Bdynamic options affect the linking of the libraries that are provided by default. To ensure that the default libraries are linked dynamically, the last use of -B should be -Bdynamic.
In a 64-bit environment, many system libraries are available only as shared dynamic libraries. These include libm.so and libc.so (libm.a and libc.a are not provided). As a result, -Bstatic and -dn may cause linking errors in 64-bit Solaris environments. Applications must link with the dynamic libraries in these cases.
The following compiler command links libfoo.a even if libfoo.so exists; all other libraries are linked dynamically:
example% CC a.o -Bstatic -lfoo -Bdynamic |
Never use -Bsymbolic with programs containing C++ code, use linker map files instead.
With -Bsymbolic, references in different modules can bind to different copies of what is supposed to be one global object.
The exception mechanism relies on comparing addresses. If you have two copies of something, their addresses won't compare equal, and the exception mechanism can fail because the exception mechanism relies on comparing what are supposed to be unique addresses.
If you compile and link in separate steps and are using the -Bbinding option, you must include the option in the link step.
-nolib, -staticlib, ld(1), Section 12.5, Statically Linking Standard Libraries, Linker and Libraries Guide
Compile only; produce object .o files, but suppress linking.
This option directs the CC driver to suppress linking with ld and produce a .o file for each source file. If you specify only one source file on the command line, then you can explicitly name the object file with the -o option.
If you enter CC -c x.cc, the x.o object file is generated.
If you enter CC -c x.cc -o y.o, the y.o object file is generated.
When the compiler produces object code for an input file (.c, .i), the compiler always produces a .o file in the working directory. If you suppress the linking step, the .o files are not removed.
Sets the major release compatibility mode of the compiler. This option controls the __SUNPRO_CC_COMPAT and __cplusplus macros.
The C++ compiler has two principal modes. The compatibility mode accepts ARM semantics and language defined by the 4.2 compiler. The standard mode accepts constructs according to the ANSI/ISO standard. These two modes are incompatible with each other because the ANSI/ISO standard forces significant, incompatible changes in name mangling, vtable layout, and other ABI details. These two modes are differentiated by the -compat option as shown in the following values.
The -compat option can have the following values.
If the -compat option is not specified, -compat=5 is assumed.
If only -compat is specified, -compat=4 is assumed.
Regardless of the -compat setting, _ _SUNPRO_CC is set to 0x540.
You cannot use the standard libraries in compatibility mode (-compat[=4]).
Use of -compat[=4] with any of the following options is not supported.
Use of -compat=5 with any of the following options is not supported.
When building a shared library in compatibility mode (-compat[=4]), do not use -Bsymbolic if the library has exceptions in it. Exceptions that should be caught might be missed.
Does not expand C++ inline functions.
Under the C++ language rules, a C++ inline function is a function for which one of the following statements is true.
Under the C++ language rules, the compiler can choose whether actually to inline a call to an inline function. The C++ compiler inlines calls to an inline function unless:
By default, the compiler may inline the functions f() and memf2() in the following code example. In addition, the class has a default compiler-generated constructor and destructor that the compiler may inline. When you use +d, the compiler will not inline f()and C::mf2(), the constructor, and the destructor.
inline int f() { return 0; } // may be inlined class C { int mf1(); // not inlined unless inline definition comes later int mf2() { return 0; } // may be inlined }; |
This option is automatically turned on when you specify -g, the debugging option.
The -g0 debugging option does not turn on +d.
The +d option has no effect on the automatic inlining that is performed when you use -xO4 or -xO5.
Defines the macro symbol name to the preprocessor.
Using this option is equivalent to including a #define directive at the beginning of the source. You can use multiple -D options.
The following table shows the predefined macros. You can use these values in such preprocessor conditionals as #ifdef.
If you do not use =def, name is defined as 1.
If +p is used, sun, unix, sparc, and i386 are not defined.
Allows or disallows dynamic libraries for the entire executable.
This option can appear only once on the command line.
If no -d option is specified, -dy is assumed.
In a 64-bit environment, many system libraries are available only as shared dynamic libraries. These include libm.so and libc.so (libm.a and libc.a are not provided). As a result, -Bstatic and -dn may cause linking errors in 64-bit Solaris environments. Applications must link with the dynamic libraries in these cases.
ld(1), Linker and Libraries Guide
SPARC: Generates double-word load and store instructions whenever possible for improved performance.
This option assumes that all double type data are double-word aligned.
If you compile one program unit with -dalign, compile all units of a program with -dalign, or you might get unexpected results.
Shows the subcommands built by driver, but does not compile.
This option directs the driver CC to show, but not execute, the subcommands constructed by the compilation driver.
Runs the preprocessor on source files; does not compile.
Directs the CC driver to run only the preprocessor on C++ source files, and to send the result to stdout (standard output). No compilation is done; no .o files are generated.
This option causes preprocessor-type line number information to be included in the output.
This option is useful for determining the changes made by the preprocessor. For example, the following program, foo.cc, generates the output shown in CODE EXAMPLE A-2.
#if __cplusplus < 199711L int power(int, int); #else template <> int power(int, int); #endif int main () { int x; x=power(2, 10); } |
example% CC -E foo.cc #4 "foo.cc" template < > int power ( int , int ) ; int main ( ) { int x ; x = power ( 2 , 10 ) ; } |
Output from this option is not supported as input to the C++ compiler when templates are used.
Controls virtual table generation in compatibility mode (-compat[=4]). Invalid and ignored when in standard mode (the default mode).
The +e option can have the following values.
|
Suppresses the generation of virtual tables and creates external references to those that are needed. |
|
|
Creates virtual tables for all defined classes with virtual functions. |
When you compile with this option, also use the -features=no%except option. Otherwise, the compiler generates virtual tables for internal types used in exception handling.
If template classes have virtual functions, ensuring that the compiler generates all needed virtual tables, but does not duplicate these tables, might not be possible.
Optimizes for speed of execution using a selection of options.
This option is a macro that selects a combination of compilation options for optimum execution speed on the machine upon which the code is compiled.
This option provides near maximum performance for many applications by expanding to the following compilation options.
The -fast macro expands into compilation options that may affect other specified options. For example, in the following command, the expansion of the -fast macro includes -xtarget=native which reverts -xarch to one of the 32-bit architecture options.
example% CC -xarch=v9 -fast test.cc |
example% CC -fast -xarch=v9 test.cc |
See the description for each option to determine possible interactions.
The code generation option, the optimization level, the optimization of built-in functions, and the use of inline template files can be overridden by subsequent options (see examples). The optimization level that you specify overrides a previously set optimization level.
The -fast option includes -fns -ftrap=%none; that is, this option turns off all trapping.
The following compiler command results in an optimization level of -xO3.
example% CC -fast -xO3 |
The following compiler command results in an optimization level of -xO5.
example% CC -xO3 -fast |
If you compile and link in separate steps, the -fast option must appear in both the compile command and the link command.
Code that is compiled with the -fast option is not portable. For example, using the following command on an UltraSPARC III system generates a binary that will not execute on an UltraSPARC II system.
example% CC -fast test.cc |
Do not use this option for programs that depend on IEEE standard floating-point arithmetic; different numerical results, premature program termination, or unexpected SIGFPE signals can occur.
In previous SPARC releases, the -fast macro expanded to -fsimple=1. Now it expands to -fsimple=2.
In previous releases, the -fast macro expanded to -xO4. Now it expands to -xO5.
-dalign, -fns, -fsimple, -ftrap=%none, -xlibmil, -nofstore, -xO5, -xlibmopt, -xtarget=native
Enables/disables various C++ language features named in a comma-separated list.
In both compatibility mode (-compat[=4]) and standard mode (the default mode), a can have the following values.
|
All the -features options that are valid for the specified mode. |
|
|
[Do not] Recognize alternative token spellings (for example, "and" for "&&"). The default is no%altspell in compatibility mode and altspell in standard mode. |
|
|
[Do not] Allow anachronistic constructs. When disabled (that is, -features=no%anachronisms), no anachronistic constructs are allowed. The default is anachronisms. |
|
|
[Do not] Allow the bool type and literals. When enabled, the macro _BOOL=1. When not enabled, the macro is not defined. The default is no%bool in compatibility mode and bool |
|
|
[Do not] Put literal strings in read-only memory. The default is no%conststrings in compatibility mode and conststrings in standard mode. |
|
|
[Do not] Allow C++ exceptions. When C++ exceptions are disabled (that is, -features=no%except), a throw-specification on a function is accepted but ignored; the compiler does not generate exception code. Note that the keywords try, throw, and catch are always reserved. See Section 8.3, Disabling Exceptions. The default is except. |
|
|
[Do not] Recognize the keyword export. The default is no%export in compatibility mode and export in standard mode. |
|
|
[Do not] allow nonstandard code that is commonly accepted by other C++ compilers. See Chapter 4 for an explanation of the invalid code that is accepted by the compiler when you use the -features=extensions option. The default is no%extensions. |
|
|
[Do not] Allow a $ symbol as a noninitial identifier character. The default is no%iddollar. |
|
|
[Do not] Use new local-scope rules for the for statement. The default is no%localfor in compatibility mode and localfor in standard mode. |
|
|
[Do not] Recognize the keyword mutable. The default is no%mutable in compatibility mode and mutable in standard mode. |
|
|
[Do not] Put initializers for nonlocal static objects into individual functions. When you use -features=no%split_init, the compiler puts all the initializers in one function. Using -features=no%split_init minimizes code size at the possible expense of compile time. The default is split_init. |
|
|
[Do not] allow ARM language constructs that are problematic in standard C++ and that may cause the program to behave differently than expected or that may be rejected by future compilers. When you use -features=no%transitions, the compiler treats these as errors. When you use -features=transitions in standard mode, the compiler issues warnings about these constructs instead of error messages. When you use -features=transitions in compatibility mode (-compat[=4]), the compiler displays the warnings about these constructs only if +w or +w2 is specified. The following constructs are considered to be transition errors: redefining a template after it was used, omitting the typename directive when it is needed in a template definition, and implicitly declaring type int. The set of transition errors may change in a future release. The default is transitions. |
|
|
Turn off all the features that can be turned off for the specified mode. |
In standard mode (the default mode), a can have the following additional values.
In compatibility mode (-compat[=4]), a can have the following additional values.
If -features is not specified, the following is assumed:
-features=%none,anachronisms,except,split_init,transitions |
-features=%all,no%iddollar,no%extensions |
This option accumulates instead of overrides.
Use of the following in standard mode (the default) is not compatible with the standard libraries and headers:
This option accumulates instead of overrides.
In compatibility mode (-compat[=4]), the -features=transitions option has no effect unless you specify the +w option or the +w2 option.
The behavior of a program might change when you use the -features=tmplife option. Testing whether the program works both with and without the -features=tmplife option is one way to test the program's portability.
The compiler assumes -features=split_init by default. If you use the -features=%none option to turn off other features, you may find it desirable to turn the splitting of initializers into separate functions back on by using -features=%none,split_init instead.
Chapter 4 and the C++ Migration Guide
Suppress the filtering that the compiler normally applies to linker error messages.
filter must be one of the following values.
If you do not specify the -filt option, or if you specify -filt without any values, then the compiler assumes -filt=errors,names,returns.
The following examples show the effects of compiling this code with the -filt option.
// filt_demo.cc class type { public: virtual ~type(); // no definition provided }; int main() { type t; } |
When you compile the code without the -filt option, the compiler assumes -filt=names,returns,errors and displays the standard output.
The following command suppresses the demangling of the of the C++ mangled linker names and suppresses the C++ explanations of linker errors.
When you specify no%names, neither returns nor no%returns has an effect.
Causes hardware traps to be enabled for floating-point overflow, division by zero, and invalid operations exceptions. These results are converted into SIGFPE signals; if the program has no SIGFPE handler, it terminates with a memory dump (unless you limit the core dump size to 0).
SPARC: In addition, -fnonstd selects SPARC nonstandard floating point.
If -fnonstd is not specified, IEEE 754 floating-point arithmetic exceptions do not abort the program, and underflows are gradual.
IA: -fnonstd expands to -ftrap=common.
SPARC: -fnonstd expands to -fns -ftrap=common.
-fns, -ftrap=common, Numerical Computation Guide.
SPARC: Enables/disables the SPARC nonstandard floating-point mode.
-fns=yes (or -fns) causes the nonstandard floating point mode to be enabled when a program begins execution.
This option provides a way of toggling the use of nonstandard or standard floating-point mode following some other macro option that includes -fns, such as -fast. (See "Examples.")
On some SPARC devices, the nonstandard floating-point mode disables "gradual underflow," causing tiny results to be flushed to zero rather than to produce subnormal numbers. It also causes subnormal operands to be silently replaced by zero.
On those SPARC devices that do not support gradual underflow and subnormal numbers in hardware, -fns=yes (or -fns) can significantly improve the performance of some programs.
The -fns option can have the following values.
If -fns is not specified, the nonstandard floating point mode is not enabled automatically. Standard IEEE 754 floating-point computation takes place--that is, underflows are gradual.
If only -fns is specified, -fns=yes is assumed.
In the following example, -fast expands to several options, one of which is -fns=yes which selects nonstandard floating-point mode. The subsequent -fns=no option overrides the initial setting and selects floating-point mode.
example% CC foo.cc -fast -fns=no |
When nonstandard mode is enabled, floating-point arithmetic can produce results that do not conform to the requirements of the IEEE 754 standard.
If you compile one routine with the -fns option, then compile all routines of the program with the -fns option; otherwise, you might get unexpected results.
This option is effective only on SPARC devices, and only if used when compiling the main program. On IA devices, the option is ignored.
Use of the -fns=yes (or -fns) option might generate the following message if your program experiences a floating-point error normally managed by the IEEE floating-point trap handlers:
Numerical Computation Guide, ieee_sun(3M)
IA: Sets the non-default floating-point precision mode.
The -fprecision option sets the rounding precision mode bits in the Floating Point Control Word. These bits control the precision to which the results of basic arithmetic operations (add, subtract, multiply, divide, and square root) are rounded.
p must be one of the following values.
If p is single or double, this option causes the rounding precision mode to be set to single or double precision, respectively, when a program begins execution. If p is extended or the -fprecision option is not used, the rounding precision mode remains at the extended precision.
The single precision rounding mode causes results to be rounded to 24 significant bits, and double precision rounding mode causes results to be rounded to 53 significant bits. In the default extended precision mode, results are rounded to 64 significant bits. This mode controls only the precision to which results in registers are rounded, and it does not affect the range. All results in register are rounded using the full range of the extended double format. Results that are stored in memory are rounded to both the range and precision of the destination format, however.
The nominal precision of the float type is single. The nominal precision of the long double type is extended.
When the -fprecision option is not specified, the rounding precision mode defaults to extended.
This option is effective only on IA devices and only if used when compiling the main program. On SPARC devices, this option is ignored.
Sets the IEEE rounding mode in effect at startup.
This option sets the IEEE 754 rounding mode that:
The meanings are the same as those for the ieee_flags subroutine, which can be used to change the mode at runtime.
r must be one of the following values.
|
Rounds towards the nearest number and breaks ties to even numbers. |
|
When the -fround option is not specified, the rounding mode defaults to -fround=nearest.
If you compile one routine with -fround=r, compile all routines of the program with the same -fround=r option; otherwise, you might get unexpected results.
This option is effective only if used when compiling the main program.
Selects floating-point optimization preferences.
This option allows the optimizer to make simplifying assumptions concerning floating-point arithmetic.
If n is present, it must be 0, 1, or 2.
If -fsimple is not designated, the compiler uses -fsimple=0.
If -fsimple is designated but no value is given for n, the compiler uses -fsimple=1.
This option can break IEEE 754 conformance.
IA: This option causes the compiler to convert the value of a floating-point expression or function to the type on the left side of an assignment rather than leave the value in a register when the following is true:
To turn off this option, use the -nofstore option.
Due to roundoffs and truncation, the results can be different from those that are generated from the register values.
Sets the IEEE trapping mode in effect at startup.
This option sets the IEEE 754 trapping modes that are established at program initialization, but does not install a SIGFPE handler. You can use ieee_handler to simultaneously enable traps and install a SIGFPE handler. When more than one value is used, the list is processed sequentially from left to right.
t can be one of the following values.
Note that the [no%] form of the option is used only to modify the meaning of the %all and common values, and must be used with one of these values, as shown in the example. The [no%] form of the option by itself does not explicitly cause a particular trap to be disabled.
If you want to enable the IEEE traps, -ftrap=common is the recommended setting.
If -ftrap is not specified, the -ftrap=%none value is assumed. (Traps are not enabled automatically.)
When one or more terms are given, the list is processed sequentially from left to right, thus -ftrap=%all,no%inexact means to set all traps except inexact.
The mode can be changed at runtime with ieee_handler(3M).
If you compile one routine with -ftrap=t, compile all routines of the program with the same -ftrap=t option; otherwise, you might get unexpected results.
Use the -ftrap=inexact trap with caution. Use of -ftrap=inexact results in the trap being issued whenever a floating-point value cannot be represented exactly. For example, the following statement generates this condition:
x = 1.0 / 3.0; |
This option is effective only if used when compiling the main program. Be cautious when using this option. If you wish to enable the IEEE traps, use -ftrap=common.
Build a dynamic shared library instead of an executable file.
All source files specified in the command line are compiled with -Kpic by default.
When building a shared library that uses templates, it is necessary in most cases to include in the shared library those template functions that are instantiated in the template data base. Using this option automatically adds those templates to the shared library as needed.
The following options are passed to ld if -c (the compile-only option) is not specified:
Do not use ld -G to build shared libraries; use CC -G. The CC driver automatically passes several options to ld that are needed for C++.
When you use the -G option, the compiler does not pass any default -l options to ld. If you want the shared library to have a dependency on another shared library, you must pass the necessary -l option on the command line. For example, if you want the shared library to be dependent upon libCrun, you must pass -lCrun on the command line.
-dy, -Kpic, -xcode=pic13, -xildoff, -ztext, ld(1) man page, Section 16.3, Building Dynamic (Shared) Libraries.
Produces additional symbol table information for debugging with dbx(1) or the Debugger and for analysis with the Performance Analyzer analyzer(1).
Instructs both the compiler and the linker to prepare the file or program for debugging and for performance analysis.
If you use this option with -xOlevel (or its equivalent options, such as -O), you will get limited debugging information. For more information, see Section A.2.131, -xOlevel.
If you use this option and the optimization level is -xO3 or lower, the compiler provides best-effort symbolic information with almost full optimization. Tail-call optimization and back-end inlining are disabled.
If you use this option and the optimization level is -xO4 or higher, the compiler provides best-effort symbolic information with full optimization.
When you specify this option, the +d option is specified automatically.
This option makes -xildon the default incremental linker option in order to speed up the compile-edit-debug cycle.
This option invokes ild in place of ld unless any of the following are true:
To use the full capabilities of the Performance Analyzer, compile with the -g option. While some performance analysis features do not require -g, you must compile with -g to view annotated source, some function level information, and compiler commentary messages. See the analyzer(1) man page and "Compiling Your Program for Data Collection and Analysis" in Program Performance Analysis Tools for more information.
The commentary messages that are generated with -g describe the optimizations and transformations that the compiler made while compiling your program. Use the er_src(1) command to display the messages, which are interleaved with the source code.
If you compile and link your program in separate steps, then including the -g option in one step and excluding it from the other step will not affect the correctness of the program, but it will affect the ability to debug the program. Any module that is not compiled with -g (or -g0), but is linked with -g (or -g0) will not be prepared properly for debugging. Note that compiling the module that contains the function main with the -g option (or the -g0 option) is usually necessary for debugging.
+d, -g0, -xildoff, -xildon, -xs, analyzer(1) man page, er_src(1) man page, ld(1) man page, Debugging a Program With dbx (for details about stabs), Program Performance Analysis Tools.
Compiles and links for debugging, but does not disable inlining.
This option is the same as -g, except that +d is disabled.
+d, -g, -xildon, Debugging a Program With dbx
Prints path names of included files.
On the standard error output (stderr), this option prints, one per line, the path name of each #include file contained in the current compilation.
Assigns the name name to the generated dynamic shared library. This is a loader option, passed to ld. In general, the name after -h should be exactly the same as the one after -o. A space between the -h and name is optional.
The compile-time loader assigns the specified name to the shared dynamic library you are creating. It records the name in the library file as the intrinsic name of the library. If there is no -hname option, then no intrinsic name is recorded in the library file.
Every executable file has a list of shared library files that are needed. When the runtime linker links the library into an executable file, the linker copies the intrinsic name from the library into that list of needed shared library files. If there is no intrinsic name of a shared library, then the linker copies the path of the shared library file instead.
example% CC -G -o libx.so.1 -h libx.so.1 a.o b.o c.o |
Add pathname to the #include file search path.
This option adds pathname to the list of directories that are searched for #include files with relative file names (those that do not begin with a slash).
The compiler searches for quote-included files (of the form #include "foo.h") in this order.
1. In the directory containing the source
2. In the directories named with -I options, if any
3. In the include directories for compiler-provided C++ header files, ANSI C header files, and special-purpose files
4. In the /usr/include directory
The compiler searches for bracket-included files (of the form #include <foo.h>) in this order.
1. In the directories named with -I options, if any
2. In the include directories for compiler-provided C++ header files, ANSI C header files, and special-purpose files
3. In the /usr/include directory
|
Note - If the spelling matches the name of a standard header file, also refer to Section 12.7.5, Standard Header Implementation. |
The -I- option allows you to override the default search rules.
If you specify -library=no%Cstd, then the compiler does not include in its search path the compiler-provided header files that are associated with the C++ standard libraries. See Section 12.7, Replacing the C++ Standard Library.
If -ptipath is not used, the compiler looks for template files in -Ipathname.
Use -Ipathname instead of -ptipath.
This option accumulates instead of overrides.
Change the include-file search rules to the following:
For include files of the form #include "foo.h", search the directories in the following order.
1. The directories named with -I options (both before and after -I-)
2. The directories for compiler-provided C++ header files, ANSI C header files, and special-purpose files
For include files of the form #include <foo.h>, search the directories in the following order.
1. The directories named in the -I options that appear after -I-
2. The directories for compiler-provided C++ header files, ANSI C header files, and special-purpose files
|
Note - If the name of the include file matches the name of a standard header, also refer to Section 12.7.5, Standard Header Implementation. |
The following example shows the results of using -I- when compiling prog.cc.
The following command shows the default behavior of searching the current directory (the directory of the including file) for include statements of the form #include "foo.h". When processing the #include "c.h" statement in inc/a.h, the compiler includes the c.h header file from the inc subdirectory. When processing the #include "c.h" statement in prog.cc, the compiler includes the c.h file from the directory containing prog.cc. Note that the -H option instructs the compiler to print the paths of the included files.
example% CC -c -Iinc -H prog.cc inc/a.h inc/c.h inc/b.h inc/c.h c.h |
The next command shows the effect of the -I- option. The compiler does not look in the including directory first when it processes statements of the form #include "foo.h". Instead, it searches the directories named by the -I options in the order that they appear in the command line. When processing the #include "c.h" statement in inc/a.h, the compiler includes the ./c.h header file instead of the inc/c.h header file.
example% CC -c -I. -I- -Iinc -H prog.cc inc/a.h ./c.h inc/b.h inc/c.h ./c.h |
When -I- appears in the command line, the compiler never searches the current directory, unless the directory is listed explicitly in a -I directive. This effect applies even for include statements of the form #include "foo.h".
Only the first -I- in a command line causes the described behavior.
Tells the linker, ld, to ignore any LD_LIBRARY_PATH setting.
Controls the placement and linkage of template instances.
a must be one of the following values.
If -instances is not specified, -instances=extern is assumed.
Section 7.3, Template Instance Placement and Linkage.
Retains temporary files created during compilation.
Along with -verbose=diags, this option is useful for debugging.
Use this option to compile source files when building a shared library. Each reference to a global datum is generated as a dereference of a pointer in the global offset table. Each function call is generated in pc-relative addressing mode through a procedure linkage table.
IA: Compiles with position-independent code.
Use this option to compile source files when building a shared library. Each reference to a global datum is generated as a dereference of a pointer in the global offset table. Each function call is generated in pc-relative addressing mode through a procedure linkage table.
Adds path to list of directories to search for libraries.
This option is passed to ld. The directory that is named by path is searched before compiler-provided directories.
This option accumulates instead of overrides.
Adds library liblib.a or liblib.so to the linker's list of search libraries.
This option is passed to ld. Normal libraries have names such as liblib.a or liblib.so, where the lib and .a or .so parts are required. You should specify the lib part with this option. Put as many libraries as you want on a single command line; they are searched in the order specified with -Ldir.
Use this option after your object file name.
This option accumulates instead of overrides.
It is always safer to put -lx after the list of sources and objects to insure that libraries are searched in the correct order.
To ensure proper library linking order, you must use -mt, rather than -lthread, to link with libthread.
If you are using POSIX threads, you must link with the -mt and -lpthread options. The -mt option is necessary because libCrun (standard mode) and libC (compatibility mode) need libthread for a multithreaded application.
-Ldir, -mt, Chapter 12, and Tools.h++ Class Library Reference
Incorporates specified CC-provided libraries into compilation and linking.
For compatibility mode (-compat[=4]), l must be one of the following values.
For standard mode (the default mode), l must be one of the following:
To link in standard mode without any C++ libraries (except libCrun), use:
example% CC -library=%none |
To include the classic-iostreams Rogue Wave tools.h++ library in standard mode:
example% CC -library=rwtools7,iostream |
To include the standard-iostreams Rogue Wave tools.h++ library in standard mode:
example% CC -library=rwtools7_std |
To include the classic-iostreams Rogue Wave tools.h++ library in compatibility mode:
example% CC -compat -library=rwtools7 |
If a library is specified with -library, the proper -I paths are set during compilation. The proper -L,-Y P, -R paths and -l options are set during linking.
This option accumulates instead of overrides.
When you use the interval arithmetic libraries, you must include one of the following libraries: libC, libCstd, or libiostream.
Use of the -library option ensures that the -l options for the specified libraries are emitted in the right order. For example, the -l options are passed to ld in the order -lrwtool -liostream for both -library=rwtools7,iostream and -library=iostream,rwtools7.
The specified libraries are linked before the system support libraries are linked.
You cannot use -library=sunperf and -xlic_lib=sunperf on the same command line.
You cannot use -library=stlport4 and -library=Cstd on the same command line.
Only one Rogue Wave tools library can be used at a time and you cannot use any Rogue Wave tools library with -library=stlport4.
When you include the classic-iostreams Rogue Wave tools library in standard mode (the default mode), you must also include libiostream (see the C++ Migration Guide for additional information). You can use the standard-iostreams Rogue Wave tools library in standard mode only. The following command examples show both valid and invalid use of the Rogue Wave tools.h++ library options.
If you include both libCstd and libiostream, you must be careful to not use the old and new forms of iostreams (for example, cout and std::cout) within a program to access the same file. Mixing standard iostreams and classic iostreams in the same program is likely to cause problems if the same file is accessed from both classic and standard iostream code.
Programs linking neither libC nor libCrun might not use all features of the C++ language.
If -xnolib is specified, -library is ignored.
If you compile and link in separate steps, the set of -library options that appear in the compile command must appear in the link command.
The set of libraries is not stable and might change from release to release.
We recommend against using the -library=%all option because:
-I, -l, -R, -staticlib, -xia, -xlang, -xnolib, Chapter 12, Chapter 13, Chapter 14, Section 2.7.3.3, Using make With Standard Library Header Files, Tools.h++ User's Guide, Tools.h++ Class Library Reference, Standard C++ Class Library Reference, C++ Interval Arithmetic Programming Reference.
For information on using the -library=no%cstd option to enable use of your own C++ standard library, see Section 12.7, Replacing the C++ Standard Library.
Removes duplicate strings from the .comment section of the object file. If the string contains blanks, the string must be enclosed in quotation marks. When you use the -mc option, the mcs -c command is invoked.
Explains where to get information about migrating source code that was built for earlier versions of the compiler.
|
Note - This option might cease to exist in the next release. |
SPARC: Permits misaligned data, which would otherwise generate an error, in memory. This is shown in the following code:
char b[100]; int f(int * ar) { return *(int *) (b +2) + *ar; } |
This option informs the compiler that some data in your program is not properly aligned. Thus, very conservative loads and stores must be used for any data that might be misaligned, that is, one byte at a time. Using this option may cause significant degradation in runtime performance. The amount of degradation is application dependent.
When using #pragma pack on a SPARC platform to pack denser than the type's default alignment, the -misalign option must be specified for both the compilation and the linking of the application.
Misaligned data is handled by a trap mechanism that is provided by ld at runtime. If an optimization flag (-xO{1|2|3|4|5} or an equivalent flag) is used with the -misalign option, the additional instructions required for alignment of misaligned data are inserted into the resulting object file and will not generate runtime misalignment traps.
If possible, do not link aligned and misaligned parts of the program.
If compilation and linking are performed in separate steps, the -misalign option must appear in both the compile and link commands.
Removes all strings from the .comment section of the object file and, if string is supplied, places string in that section. If the string contains blanks, the string must be enclosed in quotation marks.When you use this option, the command mcs -d [-a string] is invoked.
This option is not valid when either -S, -xsbfast, or -sbfast is specified.
Compiles and links for multithreaded code.
The -mt option is required if the application or libraries are multithreaded.
To ensure proper library linking order, you must use this option, rather than -lthread, to link with libthread.
If you are using POSIX threads, you must link with the -mt and -lpthread options. The -mt option is necessary because libCrun (standard mode) and libC (compatibility mode) need libthread for a multithreaded application.
If you compile and link in separate steps and you compile with -mt, be sure to link with -mt, as shown in the following example, or you might get unexpected results.
example% CC -c -mt myprog.cc example% CC -mt myprog.o |
If you are mixing parallel Fortran objects with C++ objects, the link line must specify the -mt option.
-xnolib, Chapter 11, Multithreaded Programming Guide, Linker and Libraries Guide
IA: Disables forced precision of an expression.
This option does not force the value of a floating-point expression or function to the type on the left side of an assignment, but leaves the value in a register when either of the following are true:
If no license is available, this option returns without queuing your request and without compiling. A nonzero status is returned for testing makefiles.
Does not build a runtime search path for shared libraries into the executable.
If an executable file uses shared libraries, then the compiler normally builds in a path that points the runtime linker to those shared libraries. To do so, the compiler passes the -R option to ld. The path depends on the directory where you have installed the compiler.
This option is recommended for building executables that will be shipped to customers who may have a different path for the shared libraries that are used by the program.
If you use any shared libraries under the compiler installed area (the default location is /opt/SUNWspro/lib) and you also use -norunpath, then you should either use the -R option at link time or set the environment variable LD_LIBRARY_PATH at runtime to specify the location of the shared libraries. Doing so allows the runtime linker to find the shared libraries.
Sets the name of the output file or the executable file to filename.
When the compiler must store template instances, it stores them in the template repository in the output file's directory. For example, the following command writes the object file to ./sub/a.o and writes template instances into the repository contained within ./sub/SunWS_cache.
example% CC -o sub/a.o a.cc |
The compiler reads from the template repositories corresponding to the object files that it reads. For example, the following command reads from ./sub1/SunWS_Cache and ./sub2/SunWS_cache, and, if necessary, writes to ./SunWS_cache.
example% CC sub1/a.o sub2/b.o |
For more information, see Section 7.4, The Template Repository.
The filename must have the appropriate suffix for the type of file to be produced by the compilation. It cannot be the same file as the source file, since the CC driver does not overwrite the source file.
Ignore nonstandard preprocessor asserts.
If +p is not present, the compiler recognizes nonstandard preprocessor asserts.
If +p is used, the following macros are not defined:
Only preprocesses source; does not compile. (Outputs a file with a .i suffix.)
This option does not include preprocessor-type line number information in the output.
Prepares object code to collect data for profiling with prof.
This option invokes a runtime recording mechanism that produces a mon.out file at normal termination.
If you compile and link in separate steps, the -p option must appear in both the compile command and the link command. Including -p in one step and excluding it from the other step will not affect the correctness of the program, but you will not be able to do profiling.
-xpg, -xprofile, analyzer(1) man page, Program Performance Analysis Tools.
IA: Replace with -xtarget=pentium.
Specifies an additional search directory for template source.
This option is an alternative to the normal search path set by -Ipathname. If the -ptipath option is used, the compiler looks for template definition files on this path and ignores the -Ipathname option.
Using the -Ipathname option instead of -ptipath produces less confusion.
This option accumulates instead of overrides.
This option is obsolete and is ignored by the compiler.
Even though the -ptr option is ignored, you should remove -ptr from all compilation commands because, in a later release, it may be reused with a different behavior.
For information about repository directories, see Section 7.4, The Template Repository.
Passes option to the compilation phase.
To pass multiple options, specify them in order as a comma-separated list.
phase must have one of the following values.
In the following command line, when ld is invoked by the CC driver, -Qoption passes the -i and -m options to ld.
example% CC -Qoption ld -i,-m test.c |
Be careful to avoid unintended effects. For example,
-Qoption ccfe -features=bool,iddollar |
-Qoption ccfe -features=bool -Qoption ccfe iddollar |
-Qoption ccfe -features=bool,-features=iddollar |
Causes the CC driver to produce output of the type sourcetype.
Sourcetype suffixes are defined below.
Builds dynamic library search paths into the executable file.
If the -R option is not present, the library search path that is recorded in the output object and passed to the runtime linker depends upon the target architecture instruction specified by the -xarch option (when -xarch is not present, -xarch=generic is assumed).
In a default installation, install-directory is /opt.
This option accumulates instead of overrides.
If the LD_RUN_PATH environment variable is defined and the -R option is specified, then the path from -R is scanned and the path from LD_RUN_PATH is ignored.
-norunpath, Linker and Libraries Guide
Compiles and generates only assembly code.
This option causes the CC driver to compile the program and output an assembly source file, without assembling the program. The assembly source file is named with a .s suffix.
Strips the symbol table from the executable file.
This option removes all symbol information from output executable files. This option is passed to ld.
Indicates which C++ libraries specified in the -library option (including its defaults), which libraries specified in the -xlang option, and which libraries specified by use of the -xia option are to be linked statically.
l must be one of the following values.
If -staticlib is not specified, -staticlib=%none is assumed.
The following command line links libCrun statically because Crun is a default value for -library:
example% CC -staticlib=Crun (correct) |
However, the following command line does not link libgc because libgc is not linked unless explicitly specified with the -library option:
example% CC -staticlib=gc (incorrect) |
To link libgc statically, use the following command:
example% CC -library=gc -staticlib=gc (correct) |
With the following command, the librwtool library is linked dynamically. Because librwtool is not a default library and is not selected using the -library option, -staticlib has no effect:
example% CC -lrwtool -library=iostream \ -staticlib=rwtools7 (incorrect) |
This command links the librwtool library statically:
example% CC -library=rwtools7,iostream -staticlib=rwtools7 (correct) |
This command will link the Sun Performance Libraries dynamically because -library=sunperf must be used in conjunction with -staticlib=sunperf in order for the -staticlib option to have an effect on the linking of these libraries: This command links the Sun Performance Libraries statically:
example% CC -xlic_lib=sunperf -staticlib=sunperf (incorrect) |
example% CC -library=sunperf -staticlib=sunperf (correct) |
This option accumulates instead of overrides.
The -staticlib option only works for the C++ libraries that are selected explicitly with the -xia option, the -xlang option, and the -library option, in addition to the C++ libraries that are selected implicitly by default. In compatibility mode (-compat=[4]), libC is selected by default. In standard mode (the default mode), Cstd and Crun are selected by default.
When using -xarch=v9, -xarch=v9a, or -xarch=v9b (or equivalent 64-bit architecture options), some C++ libraries are not available as static libraries.
The set of allowable values for library is not stable and might change from release to release.
-library, Section 12.5, Statically Linking Standard Libraries
Defines the directory for temporary files.
This option sets the path name of the directory for storing the temporary files that are generated during the compilation process.
Enables/disables various template options.
opt must be one of the following values.
If the -template option is not specified, -template=no%wholeclass,extdef is assumed.
Section 6.3.2, Whole-Class Instantiation, Section 7.5, Template Definition Searching
Deletes initial definition of the preprocessor symbol name.
This option removes any initial definition of the macro symbol name created by -D on the command line including those implicitly placed there by the CC driver. This option has no effect on any other predefined macros, nor on macro definitions in source files.
To see the -D options that are placed on the command line by the CC driver, add the -dryrun option to your command line.
The following command undefines the predefined symbol __sun. Preprocessor statements in foo.cc such as #ifdef(__sun) will sense that the symbol is undefined.
example% CC -U__sun foo.cc |
You can specify multiple -U options on the command line.
All -U options are processed after any -D options that are present. That is, if the same name is specified for both -D and -U on the command line, name is undefined, regardless of the order the options appear.
Compatibility mode only (-compat[=4]):
For expressions using delete[], this option generates a call to the runtime library function _vector_deletex_ instead of generating a call to _vector_delete_. The function _vector_delete_ takes two arguments: the pointer to be deleted and the size of each array element.
The function _vector_deletex_ behaves the same as _vector_delete_ except that it takes a third argument: the address of the destructor for the class. This third argument is not used by the function, but is provided to be used by third-party vendors.
The compiler generates a call to _vector_delete_ for expressions using delete[].
This is an obsolete option that will be removed in future releases. Don't use this option unless you have bought some software from a third-party vendor and the vendor recommends using this option.
v must be one of the following values.
If -verbose is not specified, -verbose=%none is assumed.
This option accumulates instead of overrides.
Identifies code that might have unintended consequences. The +w option no longer generates a warning if a function is too large to inline or if a declared program element is unused. These warnings do not identify real problems in the source, and were thus inappropriate to some development environments. Removing these warnings from +w enables more aggressive use of +w in those environments. These warnings are still available with the +w2 option.
This option generates additional warnings about questionable constructs that are:
If +w is not specified, the compiler warns about constructs that are almost certainly problems.
Some C++ standard headers result in warnings when compiled with +w.
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.
The +w2 option no longer warns about the use of implementation-dependent constructs in the system header files. Because the system header files are the implementation, the warning was inappropriate. Removing these warnings from +w2 enables more aggressive use of the option.
Some Solaris and C++ standard header files result in warnings when compiled with +w2.
Suppresses most warning messages.
This option causes the compiler not to print warning messages. However, some warnings, particularly warnings regarding serious anachronisms, cannot be suppressed.
If set at compile time, the TCOVDIR environment variable specifies the directory where the coverage (.d) files are located. If this variable is not set, then the coverage (.d) files remain in the same directory as the source files.
Use this option only for backward compatibility with old coverage files.
The -xprofile=tcov option and the -xa option are compatible in a single executable. That is, you can link a program that contains some files that have been compiled with -xprofile=tcov, and others that have been compiled with -xa. You cannot compile a single file with both options.
The -xa option is incompatible with -g.
If you compile and link in separate steps and you compile with -xa, be sure to link with -xa, or you might get unexpected results.
-xprofile=tcov, tcov(1) man page, Program Performance Analysis Tools.
(SPARC) The C++ compiler can perform type-based alias-analysis and optimizations when you specify the following command:
If you do not specify -xalias_level, the compiler sets the option to -xalias_level=any. If you specify -xalias_level but do not provide a value, the compiler sets the option to -xalias_level=compatible.
The compiler does not perform type-based alias analysis at optimization level -xO2 and below.
When building a C++ archive that uses templates, it is necessary in most cases to include in the archive those template functions that are instantiated in the template database. Using this option automatically adds those templates to the archive as needed.
The following command line archives the template functions contained in the library and object files.
example% CC -xar -o libmain.a a.o b.o c.o |
Do not add .o files from the template database on the command line.
Do not use the ar command directly for building archives. Use CC -xar to ensure that template instantiations are automatically included in the archive.
Specifies the target instruction set architecture (ISA).
This option limits the code generated by the compiler to the instructions of the specified instruction set architecture by allowing only the specified set of instructions. This option does not guarantee use of any target-specific instructions. However, use of this option may affect the portability of a binary program.
TABLE A-11 gives the details for each of the -xarch keywords on SPARC platforms.
For any particular choice, the generated executable may run much more slowly on earlier architectures. Also, although quad-precision (REAL*16 and long double) floating-point instructions are available in many of these instruction set architectures, the compiler does not use these instructions in the code it generates.
TABLE A-12 gives the details for each of the -xarch keywords on IA platforms.
If -xarch=isa is not specified, -xarch=generic is assumed.
Although this option can be used alone, it is part of the expansion of the -xtarget option and may be used to override the -xarch value that is set by a specific -xtarget option. For example, -xtarget=ultra2 expands to -xarch=v8plusa -xchip=ultra2 -xcache=16/32/1:512/64/1. In the following command -xarch=v8plusb overrides the -xarch=v8plusa that is set by the expansion of -xtarget=ultra2.
example% CC -xtarget=ultra2 -xarch=v8plusb foo.cc |
Use of -compat[=4] with -xarch=generic64, -xarch=native64, -xarch=v9, -xarch=v9a, or -xarch=v9b is not supported.
If this option is used with optimization, the appropriate choice can provide good performance of the executable on the specified architecture. An inappropriate choice, however, might result in serious degradation of performance or in a binary program that is not executable on the intended target platform.
Enables or disables better optimization of standard library calls.
By default, the functions declared in standard library headers are treated as ordinary functions by the compiler. However, some of those functions can be recognized as "intrinsic" or "built-in" by the compiler. When treated as a built-in, the compiler can generate more efficient code. For example, the compiler can recognize that some functions have no side effects, and always return the same output given the same input. Some functions can be generated inline directly by the compiler.
The -xbuiltin=%all option asks the compiler to recognize as many of the built-in standard functions as possible. The exact list of recognized functions varies with the version of the compiler code generator.
The -xbuiltin=%none option results in the default compiler behavior, and the compiler does not do any special optimizations for built-in functions.
If the -xbuiltin option is not specified, then the compiler assumes -xbuiltin=%none.
If only -xbuiltin is specified, then the compiler assumes -xbuiltin=%all.
The expansion of the macro -fast includes -xbuiltin=%all.
The following compiler command requests special handling of the standard library calls.
example% CC -xbuiltin -c foo.cc |
The following compiler command request that there be no special handling of the standard library calls. Note that the expansion of the macro -fast includes -xbuiltin=%all.
example% CC -fast -xbuiltin=%none -c foo.cc |
SPARC: Defines cache properties for use by the optimizer.
This option specifies the cache properties that the optimizer can use. It does not guarantee that any particular cache property is used.
|
Note - Although this option can be used alone, it is part of the expansion of the -xtarget option; its primary use is to override a value supplied by the -xtarget option. |
c must be one of the following values.
|
Defines the cache properties for good performance on most SPARC processors |
|
The definitions of the cache properties, si/li/ai, are as follows:
For example, i=1 designates level 1 cache properties, s1/l1/a1.
If -xcache is not specified, the default -xcache=generic is assumed. This value directs the compiler to use cache properties for good performance on most SPARC processors, without major performance degradation on any of them.
-xcache=16/32/4:1024/32/1 specifies the following:
If you compile and link in separate steps and you compile with -xcg89, be sure to link with the same option, or you might get unexpected results.
If you compile and link in separate steps and you compile with -xcg92, be sure to link with the same option, or you might get unexpected results.
SPARC: Compiling with -xcheck=stkovf adds a runtime check for stack overflow of the main thread in a singly-threaded program as well as slave-thread stacks in a multithreaded program. If a stack overflow is detected, a SIGSEGV is generated. If your application needs to handle a SIGSEGV caused by a stack overflow differently than it handles other address-space violations, see sigaltstack(2).
i must be one of the following:
If you do not specify -xcheck, the compiler defaults to -xcheck=%none.
If you specify -xcheck without any arguments, the compiler defaults to -xcheck=%none.
The -xcheck option does not accumulate on the command line. The compiler sets the flag in accordance with the last occurrence of the command.
Specifies target processor for use by the optimizer.
The -xchip option specifies timing properties by specifying the target processor. This option affects:
|
Note - Although this option can be used alone, it is part of the expansion of the -xtarget option; its primary use is to override a value supplied by the -xtarget option. |
c must be one of the following values.
|
For good performance on the system on which the compiler is running |
||
On most SPARC processors, generic is the default value that directs the compiler to use the best timing properties for good performance without major performance degradation on any of the processors.
SPARC: Specifies the code address space.
a must be one of the following values.
For SPARC V8 and V7 processors, the default is -xcode=abs32.
For SPARC and UltraSPARC processors, when you use -xarch={v9|v9a|v9b|generic64|native64}, the default is -xcode=abs64.
When you compile and link in separate steps, you must use the same -xarch option in the compile step and the link step.
SPARC: Enables optimization and inlining across source files. -xcrossfile works at compile time and involves only the files that appear on the compilation command. Consider the following command-line example:
example% CC -xcrossfile -xO4 -c f1.cc f2.cc example% CC -xcrossfile -xO4 -c f3.cc f4.cc |
Cross-module optimizations occur between files f1.cc and f2.cc, and between f3.cc and f4.cc. No optimizations occur between f1.cc and f3.cc or f4.cc.
n must be one of the following values.
|
Do not perform cross-file optimizations or cross-file inlining. |
|
Normally the scope of the compiler's analysis is limited to each separate file on the command line. For example, when the -xO4 option is passed, automatic inlining is limited to subprograms defined and referenced within the same source file.
With -xcrossfile or -xcrossfile=1, the compiler analyzes all the files named on the command line as if they had been concatenated into a single source file.
If -xcrossfile is not specified, -xcrossfile=0 is assumed and no cross-file optimizations or inlining are performed.
-xcrossfile is the same as -xcrossfile=1.
The -xcrossfile option is effective only when it is used with -xO4 or -xO5.
The files produced from this compilation are interdependent due to possible inlining, and must be used as a unit when they are linked into a program. If any one routine is changed and the files recompiled, they must all be recompiled. As a result, using this option affects the construction of makefiles.
If you compile with the -xF option and then run the Analyzer, you can generate a map file that shows an optimized order for the functions. A subsequent link to build the executable file can be directed to use that map by using the linker -Mmapfile option. It places each function from the executable file into a separate section.
Reordering the subprograms in memory is useful only when the application text page fault time is consuming a large percentage of the application time. Otherwise, reordering might not improve the overall performance of the application.
The -xF option is only supported with -features=no%except (-noex).
analyzer(1), debugger(1), ld(1) man pages
Displays a brief description of each compiler option.
Displays contents of the online readme file.
The readme file is paged by the command specified in the environment variable, PAGER. If PAGER is not set, the default paging command is more.
SPARC: Links the appropriate interval arithmetic libraries and sets a suitable floating-point environment.
|
Note - The C++ interval arithmetic library is compatible with interval arithmetic as implemented in the Fortran compiler. |
The -xia option is a macro that expands to -fsimple=0 -ftrap=%none -fns=no -library=interval.
To use the interval arithmetic libraries, include <suninterval.h>.
When you use the interval arithmetic libraries, you must include one of the following libraries: libC, Cstd, or iostreams. See -library for information on including these libraries.
If you use intervals and you specify different values for -fsimple, -ftrap, or -fns, then your program may have incorrect behavior.
C++ interval arithmetic is experimental and evolving. The specifics may change from release to release.
C++ Interval Arithmetic Programming Reference, Interval Arithmetic Solves Nonlinear Problems While Providing Guaranteed Results (http://www.sun.com/forte/info/features/intervals.html), -library
Turns off the incremental linker.
This option is assumed if you do not use the -g option. It is also assumed if you do use the -G option, or name any source file on the command line. Override this default by using the -xildon option.
-xildon, ild(1) man page, ld(1) man page, "Incremental Link Editor" in the C User's Guide
Turns on the incremental linker.
This option is assumed if you use -g and not -G, and you do not name any source file on the command line. Override this default by using the -xildoff option.
-xildoff, ild(1) man page, ld(1) man page, "Incremental Link Editor" in the C User's Guide
Specifies which user-written routines can be inlined by the optimizer at -xO3 levels or higher.
func_spec must be one of the following values.
Only routines in the file being compiled are considered for inlining unless you use -xcrossfile[=1]. The optimizer decides which of these routines are appropriate for inlining.
If the -xinline option is not specified, the compiler assumes -xinline=%auto.
If -xinline= is specified with no arguments, no functions are inlined, regardless of the optimization level.
To enable automatic inlining while disabling inlining of the function declared int foo(), use
example% CC -xO5 -xinline=%auto,no%__1cDfoo6F_i_ -c a.cc |
To strongly request the inlining of the function declared as int foo(), and to make all other functions as the candidates for inlining, use
example% CC -xO5 -xinline=%auto,__1cDfoo6F_i_ -c a.cc |
To strongly request the inlining of the function declared as int foo(), and to not allow inlining of any other functions, use
example% CC -xO5 -xinline=__1cDfoo6F_i_ -c a.cc |
The -xinline option has no effect for optimization levels below -xO3. At -xO4 and higher, the optimizer decides which functions should be inlined, and does so without the -xinline option being specified. At -xO4 and higher, the compiler also attempts to determine which functions will improve performance if they are inlined.
A routine is not inlined if any of the following conditions apply. No warnings will be omitted.
If you force the inlining of a function with -xinline, you might actually diminish performance.
Performs interprocedural optimizations.
The -xipo option performs whole-program optimizations by invoking an interprocedural analysis pass. Unlike -xcrossfile, -xipo performs optimizations across all object files in the link step, and the optimizations are not limited to just the source files on the compile command.
The -xipo option is particularly useful when compiling and linking large multifile applications. Object files compiled with this flag have analysis information compiled within them that enables interprocedural analysis across source and precompiled program files. However, analysis and optimization is limited to the object files compiled with -xipo, and does not extend to object files on libraries.
The -xipo option can have the following values.
|
Perform interprocedural aliasing analysis as well as optimizations of memory allocation and layout to improve cache performance |
If -xipo is not specified, -xipo=0 is assumed.
If only -xipo is specified, -xipo=1 is assumed.
The following example compiles and links in the same step.
example% CC -xipo -xO4 -o prog part1.cc part2.cc part3.cc |
The optimizer performs crossfile inlining across all three source files. This is done in the final link step, so the compilation of the source files need not all take place in a single compilation and could be over a number of separate compilations, each specifying the -xipo option.
The following example compiles and links in separate steps.
example% CC -xipo -xO4 -c part1.cc part2.cc example% CC -xipo -xO4 -c part3.cc example% CC -xipo -xO4 -o prog part1.o part2.o part3.o |
The object files created in the compile steps have additional analysis information compiled within them to permit crossfile optimizations to take place at the link step.
The -xipo option requires at least optimization level -xO4.
You cannot use both the -xipo option and the -xcrossfile option in the same compiler command line.
When compiling and linking are performed in separate steps, -xipo must be specified in both steps to be effective.
Objects that are compiled without -xipo can be linked freely with objects that are compiled with -xipo.
Libraries do not participate in crossfile interprocedural analysis, even when they are compiled with -xipo, as shown in this example.
example% CC -xipo -xO4 one.cc two.cc three.cc example% CC -xar -o mylib.a one.o two.o three.o ... example% CC -xipo -xO4 -o myprog main.cc four.cc mylib.a |
In this example, interprocedural optimizations will be performed between one.cc, two.cc and three.cc, and between main.cc and four.cc, but not between main.cc or four.cc and the routines in mylib.a. (The first compilation may generate warnings about undefined symbols, but the interprocedural optimizations will be performed because it is a compile and link step.)
The -xipo option generates significantly larger object files due to the additional information needed to perform optimizations across files. However, this additional information does not become part of the final executable binary file. Any increase in the size of the executable program will be due to the additional optimizations performed.
Includes the appropriate runtime libraries and ensures the proper runtime environment for the specified language.
language must be either f77, f90, or f95.
The f90 and f95 arguments are equivalent.
The -xlang=f90 and -xlang=f95 options imply -library=f90, and the -xlang=f77 option implies -library=f77. However, the -library=f77 and -library=f90 options are not sufficient for mixed-language linking because only the -xlang option ensures the proper runtime environment.
To determine which driver to use for mixed-language linking, use the following language hierarchy:
When linking Fortran 95, Fortran 77, and C++ object files together, use the driver of the highest language. For example, use the following C++ compiler command to link C++ and Fortran 95 object files.
example% CC -xlang=f95 ... |
To link Fortran 95 and Fortran 77 object files, use the Fortran 95 driver, as follows.
example% f95 -xlang=f77 ... |
You cannot use the -xlang option and the -xlic_lib option in the same compiler command. If you are using -xlang and you need to link in the Sun Performance Libraries, use -library=sunperf instead.
Do not use -xnolib with -xlang.
If you are mixing parallel Fortran objects with C++ objects, the link line must specify the -mt flag.
Causes libm to return IEEE 754 values for math routines in exceptional cases.
The default behavior of libm is XPG-compliant.
Inlines selected libm library routines for optimization.
There are inline templates for some of the libm library routines. This option selects those inline templates that produce the fastest executables for the floating-point option and platform currently being used.
This option is implied by the -fast option.
-fast, Numerical Computation Guide
Uses library of optimized math routines.
This option uses a math routine library optimized for performance and usually generates faster code. The results might be slightly different from those produced by the normal math library; if so, they usually differ in the last bit.
The order on the command line for this library option is not significant.
This option is implied by the -fast option.
SPARC: Links in the Sun Performance Library
.
This option, like -l, should appear at the end of the command line, after source or object files.
You cannot use the -xlang option and the -xlic_lib option in the same compiler command. If you are using -xlang and you need to link in the Sun Performance Library, use -library=sunperf instead.
You cannot use -library=sunperf and -xlic_lib=sunperf in the same compiler command.
The recommended method for statically linking the Sun Performance Library is to use the -library=sunperf and -staticlib=sunperf options, as in the following example.
example% CC -library=sunperf -staticlib=sunperf ... (recommended) |
If you choose to use the -xlic_lib=sunperf option instead of -library=sunperf, then use the -Bstatic option, as shown in the following example.
% CC ... -Bstatic -xlic_lib=sunperf -Bdynamic ... |
-library and the performance_library readme
Shows license server information.
This option returns the license-server name and the user ID for each user who has a license checked out.
Outputs makefile dependency information.
The program foo.cc contains the following statement:
#include "foo.h" |
When foo.c is compiled with the -xM, the output includes the following line:
foo.o : foo.h |
make(1S) (for details about makefiles and dependencies)
This option is the same as -xM, except that it does not report dependencies for the /usr/include header files, and it does not report dependencies for compiler-supplied header files.
SPARC: Merges the data segment with the text segment.
The data in the object file is read-only and is shared between processes, unless you link with ld -N.
Use the -xnativeconnect option when you want to include interface information inside object files and subsequent shared libraries so that the shared library can interface with code written in the Java[tm] programming language (Java code). You must also include -xnativeconnect when you build the shared library with -G.
When you compile with -xnativeconnect, you are providing the maximum, external, visibility of the native code interfaces. The Native Connector Tool (NCT) enables the automatic generation of Java code and Java Native Interface (JNI) code so that C++ shared libraries can be called from Java code. For more information on how to use the NCT, see the Forte Developer online help.
i must be one of the following:
CC -xnativeconnect=inlines first.o -xnativeconnect=interfaces second.o -O -G -o library.so |
Do not compile with -compat=4 if you plan to use -xnativeconnect. Remember that if you specify -compat without any arguments, the compiler sets it to -compat=4. If you do not specify -compat, the compiler sets it to -compat=5. You can also explicitly set the compatibility mode by issuing -compat=5.
Disables linking with default system libraries.
Normally (without this option), the C++ compiler links with several system libraries to support C++ programs. With this option, the -llib options to link the default system support libraries are not passed to ld.
Normally, the compiler links with the system support libraries in the following order:
-lCstd -lCrun -lm -lw -lcx -lc |
-lC -lm -lw -lcx -lc |
The order of the -l options is significant. The -lm, -lw, and -lcx options must appear before -lc.
|
Note - If the -mt compiler option is specified, the compiler normally links with -lthread just before it links with -lm. |
To determine which system support libraries will be linked by default, compile with the -dryrun option. For example, the output from the following command:
example% CC foo.cc -xarch=v9 -dryrun |
Includes the following in the output:
-lCstd -lCrun -lm -lw -lc |
Note that when -xarch=v9 is specified, -lcx is not linked.
For minimal compilation to meet the C application binary interface (that is, a C++ program with only C support required), use:
example% CC -xnolib test.cc -lc |
To link libm statically into a single-threaded application with the generic architecture instruction set, use:
example% CC -xnolib test.cc -lCstd -lCrun -Bstatic -lm \ -Bdynamic -lw -lcx -lc |
example% CC -compat -xnolib test.cc -lC -Bstatic -lm \ -Bdynamic -lw -lcx -lc |
Some static system libraries, such as libm.a and libc.a, are not available when linking with -xarch=v9, -xarch=v9a or -xarch=v9b.
If you specify -xnolib, you must manually link all required system support libraries in the given order. You must link the system support libraries last.
If -xnolib is specified, -library is ignored.
Many C++ language features require the use of libC (compatibility mode) or libCrun (standard mode).
This set of system support libraries is not stable and might change from release to release.
In 64-bit compilation modes, -lcx is not present.
Cancels -xlibmil on the command line.
Use this option with -fast to override linking with the optimized math library.
Does not use the math routine library.
Use this option after the -fast option on the command line, as in this example:
example% CC -fast -xnolibmopt |
SPARC: The C++ compiler implements the OpenMP interface for explicit parallelization including a set of source code directives, run-time library routines, and environment variables with the following option:
If you do not specify -xopenmp, the compiler sets the option to -xopenmp=none.
If you specify only -xopenmp, the compiler sets the option to -xopenmp=parallel which enables recognition of OpenMP pragmas and applies to SPARC only. The optimization level under -xopenmp=parallel is -x03. The compiler issues a warning if the optimization level of your program is changed from a lower level to -x03.
The -xopenmp=stubs command links with the stubs routines for the OpenMP API routines. Use this options if you need to compile your application to execute serially. The -xopenmp=stubs command also defines the _OPENMP preprocessor token.
The -xopenmp=none command does not enable recognition of OpenMP pragmas, makes no change to the optimization level of your program, and does not predefine any preprocessor tokens.
Specifies optimization level. In general, program execution speed depends on the level of optimization. The higher the level of optimization, the faster the speed.
If -xOlevel is not specified, only a very basic level of optimization (limited to local common subexpression elimination and dead code analysis) is performed. A program's performance might improve significantly when it is compiled with an optimization level. The use of -xO2 (or the equivalent options -O and -O2) is recommended for most programs.
Generally, the higher the level of optimization with which a program is compiled, the better the runtime performance. However, higher optimization levels can result in increased compilation time and larger executable files.
In a few cases, -xO2 might perform better than the others, and -xO3 might outperform -xO4. Try compiling with each level to see if you have one of these rare cases.
If the optimizer runs out of memory, it tries to recover by retrying the current procedure at a lower level of optimization. The optimizer resumes subsequent procedures at the original level specified in the -xOlevel option.
There are five levels that you can use with -xO. The following sections describe how they operate on the SPARC platform and the IA platform.
If you use -g or -g0 and the optimization level is -xO3 or lower, the compiler provides best-effort symbolic information with almost full optimization. Tail-call optimization and back-end inlining are disabled.
If you use -g or -g0 and the optimization level is -xO4 or higher, the compiler provides best-effort symbolic information with full optimization.
Debugging with -g does not suppress -xOlevel, but -xOlevel limits -g in certain ways. For example, the -xOlevel options reduce the utility of debugging so that you cannot display variables from dbx, but you can still use the dbx where command to get a symbolic traceback. For more information, see Debugging a Program With dbx.
The -xcrossfile option is effective only if it is used with -xO4 or -xO5.
The -xinline option has no effect for optimization levels below -xO3. At -xO4, the optimizer decides which functions should be inlined, and does so regardless of whether you specify the -xinline option. At -xO4, the compiler also attempts to determine which functions will improve performance if they are inlined. If you force the inlining of a function with -xinline, you might actually diminish performance.
If you optimize at -xO3 or -xO4 with very large procedures (thousands of lines of code in a single procedure), the optimizer might require an unreasonable amount of memory. In such cases, machine performance can be degraded.
To prevent this degradation from taking place, use the limit command to limit the amount of virtual memory available to a single process (see the csh(1) man page). For example, to limit virtual memory to 16 megabytes:
example% limit datasize 16M |
This command causes the optimizer to try to recover if it reaches 16 megabytes of data space.
The limit cannot be greater than the total available swap space of the machine, and should be small enough to permit normal use of the machine while a large compilation is in progress.
The best setting for data size depends on the degree of optimization requested, the amount of real memory, and virtual memory available.
To find the actual swap space, type: swap -l
To find the actual real memory, type: dmesg | grep mem
-fast, -xcrossfile=n, -xprofile=p, csh(1) man page
The -xpg option compiles self-profiling code to collect data for profiling with gprof. This option invokes a runtime recording mechanism that produces a gmon.out file when the program normally terminates.
If you compile and link separately, and you compile with -xpg, be sure to link with -xpg.
-xprofile=p, analyzer(1) man page, Program Performance Analysis Tools.
SPARC: Enable prefetch instructions on those architectures that support prefetch, such as UltraSPARC II (-xarch=v8plus, v8plusa, v9plusb, v9, v9a, or v9b)
a must be one of the following values.
|
Adjust the compiler's assumed prefetch-to-load and prefetch-to-store latencies by the specified factor. The factor must be a positive floating-point or integer number. |
|
With -xprefetch, -xprefetch=auto, and -xprefetch=yes, the compiler is free to insert prefetch instructions into the code it generates. This may result in a performance improvement on architectures that support prefetch.
If you are running computationally intensive codes on large multiprocessors, you might find it advantageous to use -xprefetch=latx:factor. This option instructs the code generator to adjust the default latency time between a prefetch and its associated load or store by the specified factor.
The prefetch latency is the hardware delay between the execution of a prefetch instruction and the time the data being prefetched is available in the cache. The compiler assumes a prefetch latency value when determining how far apart to place a prefetch instruction and the load or store instruction that uses the prefetched data.
|
Note - The assumed latency between a prefetch and a load may not be the same as the assumed latency between a prefetch and a store. |
The compiler tunes the prefetch mechanism for optimal performance across a wide range of machines and applications. This tuning may not always be optimal. For memory-intensive applications, especially applications intended to run on large multiprocessors, you may be able to obtain better performance by increasing the prefetch latency values. To increase the values, use a factor that is greater than 1 (one). A value between .5 and 2.0 will most likely provide the maximum performance.
For applications with datasets that reside entirely within the external cache, you may be able to obtain better performance by decreasing the prefetch latency values. To decrease the values, use a factor that is less than 1 (one).
To use the -xprefetch=latx:factor option, start with a factor value near 1.0 and run performance tests against the application. Then increase or decrease the factor, as appropriate, and run the performance tests again. Continue adjusting the factor and running the performance tests until you achieve optimum performance. When you increase or decrease the factor in small steps, you will see no performance difference for a few steps, then a sudden difference, then it will level off again.
If -xprefetch is not specified, -xprefetch=no%auto,explicit is assumed.
If only -xprefetch is specified, -xprefetch=auto,explicit is assumed.
The default of no%auto is assumed unless explicitly overridden with the use of -xprefetch without any arguments or with an argument of auto or yes. For example, -xprefetch=explicit is the same as -xprefetch=explicit,no%auto.
The default of explicit is assumed unless explicitly overridden with an argument of no%explicit or an argument of no. For example, -xprefetch=auto is the same as -xprefetch=auto,explicit.
If automatic prefetching is enabled, such as with -xprefetch or -xprefetch=yes, but a latency factor is not specified, then -xprefetch=latx:1.0 is assumed.
This option accumulates instead of overrides.
The sun_prefetch.h header file provides the macros for specifying explicit prefetch instructions. The prefetches will be approximately at the place in the executable that corresponds to where the macros appear.
To use the explicit prefetch instructions, you must be on the correct architecture, include sun_prefetch.h, and either exclude -xprefetch from the compiler command or use -xprefetch, -xprefetch=auto,explicit, -xprefetch=explicit or -xprefetch=yes.
If you call the macros and include the sun_prefetch.h header file, but pass -xprefetch=no%explicit or -xprefetch=no, the explicit prefetches will not appear in your executable.
The use of latx:factor is valid only when automatic prefetching is enabled. That is, latx:factor is ignored unless you use it in conjunction with yes or auto, as in -xprefetch=yes,latx:factor.
Explicit prefetching should only be used under special circumstances that are supported by measurements.
Because the compiler tunes the prefetch mechanism for optimal performance across a wide range of machines and applications, you should only use -xprefetch=latx:factor when the performance tests indicate there is a clear benefit. The assumed prefetch latencies may change from release to release. Therefore, retesting the effect of the latency factor on performance whenever switching to a different release is highly recommended.
Use the new -xprefetch_level=i option to control the aggressiveness of the automatic insertion of prefetch instructions as determined with -xprefetch=auto. The compiler becomes more aggressive, or in other words, introduces more prefetches, with each higher, level of -xprefetch_level.
The appropriate value for -xprefetch_level depends on the number of cache misses your application has. Higher -xprefetch_level values have the potential to improve the performance of applications with a high number of cache misses.
The default is -xprefetch_level=2 when you specify -xprefetch=auto.
This option is effective only when it is compiled with -xprefetch=auto, with optimization level 3 or greater (-xO3), and on a platform that supports prefetch (v8plus, v8plusa, v9, v9a, v9b, generic64, native64).
Collects or optimizes with runtime profiling data.
This option causes execution frequency data to be collected and saved during the execution. The data can then be used in subsequent runs to improve performance. This option is valid only when a level of optimization is specified.
p must be one of the following values.
The -xprofile=tcov and the -xa options are compatible in a single executable. That is, you can link a program that contains some files that have been compiled with -xprofile=tcov and other files compiled with -xa. You cannot compile a single file with both options.
The code coverage report produced by -xprofile=tcov can be unreliable if there is inlining of functions due to the use of -xinline or -xO4.
You can set the environment variables $SUN_PROFDATA and $SUN_PROFDATA_DIR to control where a program that is compiled with -xprofile=collect puts the profile data. If these variables are not set, the profile data is written to name.profile/feedback in the current directory (name is the name of the executable or the name specified in the -xprofile=collect:name flag). If these variables are set, the -xprofile=collect data is written to $SUN_PROFDATA_DIR/$SUN_PROFDATA.
The $SUN_PROFDATA and $SUN_PROFDATA_DIR environment variables similarly control the path and names of the profile data files written by tcov. See the tcov(1) man page for more information.
If you compile and link in separate steps, the same -xprofile option must appear in both the compile command and the link command. Including -xprofile in one step and excluding it from the other step will not affect the correctness of the program, but you will not be able to do profiling.
-xa, tcov(1) man page, Program Performance Analysis Tools.
SPARC: Controls scratch register usage.
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.
r must be one of the following values. The meaning of each value depends upon the -xarch setting.
If -xregs is not specified, -xregs=appl,float is assumed.
To compile an application program using all available scratch registers, use -xregs=appl,float.
To compile non-floating-point code that is sensitive to context switch, use -xregs=no%appl,no%float.
Allows debugging by dbx without object (.o) files.
This option disables Auto-Read for dbx. Use this option if you cannot keep the .o files. This option passes the -s option to the assembler.
No Auto-Read is the older way of loading symbol tables. It places all symbol tables for dbx in the executable file. The linker links more slowly, and dbx initializes more slowly.
Auto-Read is the newer and default way of loading symbol tables. With Auto-Read the information is placed in the .o files, so that dbx loads the symbol table information only if it is needed. Hence the linker links faster, and dbx initializes faster.
With -xs, if you move executables to another directory, you do not have to move the object (.o) files to use dbx.
Without -xs, if you move the executables to another directory, you must move both the source files and the object (.o) files to use dbx.
SPARC: Allows the compiler to assume that no memory protection violations occur.
This option is effective only when it is used with -xO5 optimization and -xarch=v8plus, v8plusa, v8plusb, v9, v9a, or v9b is specified.
Because nonfaulting loads do not cause a trap when a fault such as address misalignment or segmentation violation occurs, you should use this option only for programs in which such faults cannot occur. Because few programs incur memory-based traps, you can safely use this option for most programs. Do not use this option for programs that explicitly depend on memory-based traps to handle exceptional conditions.
This option causes the CC driver to generate extra symbol table information in the SunWS_cache subdirectory for the source browser.
Produces only source browser information, no compilation.
This option runs only the ccfe phase to generate extra symbol table information in the SunWS_cache subdirectory for the source browser. No object file is generated.
SPARC: Does not allow optimizations that increase code size.
Specifies the target platform for instruction set and optimization.
The performance of some programs can benefit by providing the compiler with an accurate description of the target computer hardware. When program performance is critical, the proper specification of the target hardware could be very important. This is especially true when running on the newer SPARC processors. However, for most programs and older SPARC processors, the performance gain is negligible and a generic specification is sufficient.
On SPARC platforms, t must be one of the following values.
|
Gets the best performance on the host system. The compiler generates code optimized for the host system. It determines the available architecture, chip, and cache properties of the machine on which the compiler is running. |
|
|
Gets the best performance for 64-bit object binaries on the host system. The compiler generates 64-bit object binaries optimized for the host system. It determines the available 64-bit architecture, chip, and cache properties of the machine on which the compiler is running. |
|
|
Gets the best performance for generic architecture, chip, and cache. The compiler expands -xtarget=generic to: |
|
|
Sets the parameters for the best performance of 64-bit object binaries over most 64-bit platform architectures. |
|
|
Gets the best performance for the specified platform. Select a SPARC platform name from TABLE A-21. |
The following table details the -xtarget SPARC platform names and their expansions.
On IA platforms, t must be one of the following values.
The following table lists the -xtarget values for the Intel Architecture:
On both SPARC and IA devices, if -xtarget is not specified, -xtarget=generic is assumed.
The -xtarget option is a macro that permits a quick and easy specification of the -xarch, -xchip, and -xcache combinations that occur on commercially purchased platforms. The only meaning of -xtarget is in its expansion.
-xtarget=sun4/15 means -xarch=v8a -xchip=micro -xcache=2/16/1.
Compilation for SPARC V9 architecture indicated by the -xarch=v9|v9a|v9b option. Setting -xtarget=ultra or ultra2 is not necessary or sufficient. If -xtarget is specified, the -xarch=v9, v9a, or v9b option must appear after the -xtarget. For example:
-xarch=v9 -xtarget=ultra |
expands to the following and reverts the -xarch value to v8.
-xarch=v9 -xarch=v8 -xchip=ultra -xcache=16/32/1:512/64/1 |
The correct method is to specify -xarch after -xtarget. For example:
-xtarget=ultra -xarch=v9 |
When you compile and link in separate steps, you must use the same -xtarget settings in the compile step and the link step.
Causes the CC driver to report execution time for the various compilation passes.
Enables unrolling of loops where possible.
This option specifies whether or not the compiler optimizes (unrolls) loops.
When n is 1, it is a suggestion to the compiler to not unroll loops.
When n is an integer greater than 1, -unroll=n causes the compiler to unroll loops n times.
Enables or disables recognition of trigraph sequences as defined by the ISO/ANSI C standard.
If your source code has a literal string containing question marks (?) that the compiler is interpreting as a trigraph sequence, you can use the -xtrigraph=no suboption to turn off the recognition of trigraph sequences.
|
Enables recognition of trigraph sequences throughout the compilation unit |
|
|
Disables recognition of trigraph sequences throughout the compilation unit |
When you do not include the -xtrigraphs option on the command line, the compiler assumes -xtrigraphs=yes.
If only -xtrigraphs is specified, the compiler assumes -xtrigraphs=yes.
Consider the following example source file named trigraphs_demo.cc.
#include <stdio.h> int main () { (void) printf("(\?\?) in a string appears as (??)\n"); return 0; } |
Here is the output if you compile this code with -xtrigraphs=yes.
example% CC -xtrigraphs=yes trigraphs_demo.cc example% a.out (??) in a string appears as (] |
Here is the output if you compile this code with -xtrigraphs=no.
example% CC -xtrigraphs=no trigraphs_demo.cc example% a.out (??) in a string appears as (??) |
For information on trigraphs, see the C User's Guide chapter about transitioning to ANSI/ISO C.
Converts all warnings to errors by returning nonzero exit status.
Link editor option. For more information, see the ld(1) man page and the Solaris Linker and Libraries Guide.
| C++ User's Guide | 816-2460-10 |
|
Copyright © 2002, Sun Microsystems, Inc. All rights reserved.