| 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