This chapter describes the C compiler options in alphabetical order. See Appendix A, Compiler Options Grouped by Functionality for options grouped by functionality. For example, Table A–1 lists all the optimization and performance options.
The C compiler recognizes by default some of the constructs of the 2011 ISO/IEC C standard. The supported features are detailed in Appendix C, Features of C11. Use the -std command if you want to limit the compiler to a previous version of ISO/IEC C standard.
The syntax of the cc command is:
% cc [options] filenames [libraries]...
where:
options represents one or more of the options described in Table A–14.
filenames represents one or more files used in building the executable program
The C compiler accepts a list of C source files and object files contained in the list of files specified by filenames. The resulting executable code is placed in a.out, unless the -o option is used. In this case, the code is placed in the file named by the -o option.
Use the C compiler to compile and link any combination of the following:
C source files, with a .c suffix
Inline template files, with a .il suffix (only when specified with .c files)
C preprocessed source files, with a .i suffix
Object-code files, with .o suffixes
Assembler source files, with .s suffixes
After linking, the C compiler places the linked files, now in executable code, into a file named a.out, or into the file specified by the -o option. When the compiler produces object code for each .i or .c input file, it always creates an object (.o) file in the current working directory.
libraries represents any of a number of standard or user-provided libraries containing functions, macros, and definitions of constants.
Use the option -YP, dir to change the default directories used for finding libraries. dir is a colon-separated path list. The default library search order can be seen by using the -### or -xdryrun option and examining the -Y option of the ld invocation.
cc uses getopt to parse command-line options. Options are treated as a single letter or a single letter followed by an argument. See thegetopt(3c) man page.
This section describes the cc options, arranged alphabetically. These descriptions are also available 0n the cc(1) man page. Use the cc -flags option for a one-line summary of these descriptions.
Options noted as being unique to one or more platforms are accepted without error and ignored on all other platforms.
Enables verbose mode, showing how command options expand. Shows each component as it is invoked.
Shows each component as it would be invoked, but does not actually execute it. Also shows how command options would expand.
Associates name as a predicate with the specified tokens as if by a #assert preprocessing directive. Preassertions:
system(unix)
machine(sparc) (SPARC)
machine(i386) (x86)
cpu(sparc) (SPARC)
cpu(i386) (x86)
These preassertions are not valid in -pedantic mode.
-A followed only by a dash (-) causes all predefined macros (other than those that begin with __) and predefined assertions to be ignored.
Equivalent to -std=c89.
Specifies whether bindings of libraries for linking are static or dynamic, indicating whether libraries are non-shared or shared, respectively.
–Bdynamic causes the link editor to look for files named libx.so and then for files named libx.a when given the -lx option.
–Bstatic causes the link editor to look only for files named libx.a. This option may be specified multiple times on the command line as a toggle. This option and its argument are passed to ld(1).
This option and its argument are passed to the linker.
Prevents the C preprocessor from removing comments, except those on the preprocessing directive lines.
Directs the C compiler to suppress linking with ld(1) and to produce a .o file for each source file. You can explicitly name a single object file using the-o option. When the compiler produces object code for each .i or .c input file, it always creates an object (.o) file in the current working directory. If you suppress the linking step, you also suppress the removal of the object files.
Define a macro with optional arguments as if the macro is defined by a #define preprocessing directive. If no =expansion is specified, the compiler assumes 1.
See the cc(1) man page for a list of compiler predefined macros.
-dy specifies dynamic linking, which is the default, in the link editor.
-dn specifies static linking in the link editor.
This option and its arguments are passed to ld(1).
(SPARC) Obsolete. You should not use this option. Use -xmemalign=8s instead. See -xmemalign=ab for more information. For a complete list of obsolete options, see Obsolete Options. This option is silently ignored on x86 platforms.
Runs the source file through the preprocessor only and sends the output to stdout. The preprocessor is built directly into the compiler, except in -Xs mode, where /usr/ccs/lib/cpp is invoked. Includes the preprocessor line numbering information. See also the description of the -P option.
Use this option if you want to prefix the string “error:” to the beginning of error messages so they are more easily distinguishable from warning messages. The prefix is also attached to warnings that are converted to errors by -errwarn.
|
If you do not specify this option, the compiler sets it to -errfmt=no%error. If you specify –errfmt but do not supply a value, the compiler sets it to -errfmt=error.
Limits the warnings from header files to the group of header files indicated by the flags in the following table:
|
This command suppresses C compiler warning messages and has no effect on error messages. This option applies to all warning messages regardless of whether they have been designated by -errwarn to cause a non-zero exit status.
t is a comma-separated list that consists of one or more of the following: tag, no%tag, %all, %none. Order is important; for example, %all,no%tag suppresses all warning messages except tag. The following table lists the -erroff values.
|
The default is -erroff=%none. Specifying -erroff is equivalent to specifying -erroff=%all.
Only warning messages from the C compiler front-end that display a tag when the -errtags option is used can be suppressed with the -erroff option. You can achieve finer control over error message suppression. See error_messages.
Use this option to control how much detail is in the error message produced by the compiler when it discovers a type mismatch. This option is particularly useful when the compiler discovers a type mismatch that involves a large aggregate.
i can be one of the values listed in the following table.
|
If you do not specify -errshort, the compiler sets the option to -errshort=full. If you specify -errshort but do not provide a value, the compiler sets the option to -errshort=tags.
This option does not accumulate. It accepts the last value specified on the command line.
Displays the message tag for each warning message of the C compiler front-end that can be suppressed with the -erroff option or made a fatal error with the -errwarn option. Messages from the C compiler driver and other components of the C compilation system do not have error tags, and cannot be suppressed with -erroff and made fatal with -errwarn.
a can be either yes or no. The default is -errtags=no. Specifying -errtags is equivalent to specifying -errtags=yes.
Use the -errwarn option to cause the C compiler to exit with a failure status for the given warning messages.
t is a comma-separated list that consists of one or more of the following: tag, no%tag, %all, %none. Order is important; for example %all,no%tag causes cc to exit with a fatal status if any warning except tag is issued.
The warning messages generated by the C compiler change from release to release as the compiler error checking improves and features are added. Code that compiles using -errwarn=%all without error might not compile without error in the next release of the compiler.
Only warning messages from the C compiler front-end that display a tag when the -errtags option is used can be specified with the -errwarn option to cause the C compiler to exit with a failure status.
The following table details the -errwarn values:
|
The default is -errwarn=%none. Specifying -errwarn alone is equivalent to -errwarn=%all.
This option is a macro that can be effectively used as a starting point for tuning an executable for maximum runtime performance. The -fast option macro can change from one release of the compiler to the next and expands to options that are target platform specific. Use the -# option or -xdryrun to examine the expansion of -fast, and incorporate the appropriate options of -fast into the ongoing process of tuning the executable.
The expansion of -fast includes the -xlibmopt option, which enables the compiler to use a library of optimized math routines. For more information, see -xlibmopt.
The -fast option impacts the value of errno. See Preserving the Value of errno for more information.
Modules that are compiled with -fast must also be linked with -fast. For a complete list of all compiler options that must be specified at both compile time and at link time, see Compile-Time and Link-Time Options.
The –fast option is unsuitable for programs intended to run on a different target than the compilation machine. In such cases, follow -fast with the appropriate -xtarget option. For example:
cc -fast -xtarget=generic ...
For C modules that depend on exception handling specified by SUID, follow -fast by -xnolibmil:
% cc -fast -xnolibmil
With -xlibmil, exceptions cannot be noted by setting errno or calling matherr(3m).
The –fast option is unsuitable for programs that require strict conformance to the IEEE 754 Standard.
The following table lists the set of options selected by -fast across platforms.
|
The optimizations performed by these options might alter the behavior of programs from that defined by the ISO C and IEEE standards. See the description of the specific option for details.
The -fast flag acts like a macro expansion on the command line. Therefore, you can override the optimization level and code generation option aspects by following -fast with the desired optimization level or code generation option. Compiling with the -fast -xO4 pair is like compiling with the -xO2 -xO4 pair. The latter specification takes precedence.
On x86, the -fast option includes -xregs=frameptr. See the discussion of this option for details, especially when compiling mixed C, Fortran, and C++ source codes.
Do not use this option for programs that depend on IEEE standard exception handling; you can get different numerical results, premature program termination, or unexpected SIGFPE signals.
To see the actual expansion of —fast on a running platform, use the following command:
% cc -fast -xdryrun |& grep ###
Reports K&R-style function definitions and declarations.
The following table lists acceptable values for v.
|
Old C and C++ objects (created with Solaris Studio compilers prior to this release) can be linked with new C and C++ objects with no change of behavior for the old objects. To get standard conforming behavior, you must recompile old code with the current compiler.
typeof(int) i;/* declares variable "i" to be type int*/ typeof(i+10) j;/* declares variable "j" to be type int, the type of the expression */ i = sizeof(typeof(j)); /* sizeof returns the size of the type associated with variable "j" */ int a[10]; typeof(a) b;/* declares variable "b" to be array of size 10 */
The typeof operator can be especially useful in macro definitions, where arguments may be of arbitrary type. For example:
#define SWAP(a,b) { typeof(a) temp; temp = a; a = b; b = temp; }
Prints a brief summary of each available compiler option.
(x86) Use this option to control how floating-point expressions are evaluated.
|
If you do not specify -flteval, the compiler sets it to -flteval=any. If you do specify -flteval but do not provide a value, the compiler sets it to -flteval=2.
-flteval=2 is only usable with -xarch=sse, pentium_pro, ssea, or pentium_proa. -flteval=2 is also not compatible in combination with options -fprecision or -nofstore.
See also Precision of Floating Point Evaluators.
Enables automatic generation of floating-point fused multiply-add instructions. –fma=none disables generation of these instructions. –fma=fused allows the compiler to attempt to find opportunities to improve the performance of the code by using floating-point fused multiply-add instructions.
The default is –fma=none.
The minimum architecture requirement is –xarch=sparcfmaf on SPARC and -xarch=avx2 on x86 to generate fused multiply-add instructions. The compiler marks the binary program if fused multiply-add instructions are generated in order to prevent the program from executing on platforms that do not support fused multiply-add instructions. When the minimum architecture is not used, then -fma=fused has no effect.
Fused multiply-add instructions eliminate the intermediate rounding step between the multiply and add. Consequently, programs may produce different results when compiled with –fma=fused, although precision will tend to increase rather than decrease.
This option is a macro for -fns and -ftrap=common.
On SPARC platforms, this option enables nonstandard floating-point mode.
For x86 platforms, this option selects SSE flush-to-zero mode and, where available, denormals-are-zero mode, which causes subnormal results to be flushed to zero, and, where available, this option also causes subnormal operands to be treated as zero. This option has no effect on traditional x86 floating-point operations that do not utilize the SSE or SSE2 instruction set.
The default is -fns=no, standard floating-point mode. -fns is the same as -fns=yes.
Optional use of =yes or =no provides a way of toggling the -fns flag following some other macro flag that includes -fns, such as -fast.
On some SPARC systems, the nonstandard floating point mode disables “gradual underflow,” causing tiny results to be flushed to zero rather than producing subnormal numbers. It also causes subnormal operands to be replaced silently by zero. On those SPARC systems that do not support gradual underflow and subnormal numbers in hardware, use of this option can significantly improve the performance of some programs.
When nonstandard mode is enabled, floating point arithmetic may produce results that do not conform to the requirements of the IEEE 754 standard. See the Numerical Computation Guide for more information.
On SPARC systems, this option is effective only if used when compiling the main program.
Same as -xopenmp=parallel.
Equivalent to -KPIC
Equivalent to -Kpic
(x86) -fprecision= {single, double, extended}
Initializes the rounding-precision mode bits in the Floating-point Control Word to single (24 bits), double (53 bits), or extended (64 bits), respectively. The default floating-point rounding-precision mode is extended.
Note that on x86, only the precision, not exponent, range is affected by the setting of floating-point rounding precision mode.
This option is effective only on x86 systems and only if used when compiling the main program, but is ignored if compiling for 64–bit (-m64) or SSE2–enabled (-xarch=sse2) processors. It is also ignored on SPARC systems.
Sets the IEEE 754 rounding mode that is established at runtime during the program initialization.
r must be one of: nearest, tozero, negative, positive.
The default is -fround=nearest.
The meanings are the same as those for the ieee_flags subroutine.
When r is tozero, negative, or positive, this flag sets the rounding direction mode to round-to-zero, round-to-negative-infinity, or round-to-positive-infinity respectively when a program begins execution. When r is nearest or the -fround flag is not used, the rounding direction mode is not altered from its initial value (round-to-nearest by default).
This option is effective only if used when compiling the main program.
Enables the optimizer to make simplifying assumptions concerning floating-point arithmetic.
The compiler defaults to -fsimple=0. Specifying -fsimple, is equivalent to -fsimple=1.
If n is present, it must be 0, 1, or 2.
|
Even with -fsimple=2, the optimizer is not permitted to introduce a floating-point exception in a program that otherwise produces none.
See Techniques for Optimizing Applications: High Performance Computing by Rajat Garg and Ilya Sharapov for a more detailed explanation of how optimization can affect precision.
(-Xt and -Xs modes only) By default -Xs and -Xt follow the K&R C rules for float expressions, by promoting them to double and evaluating them in double precision. Use -fsingle when specifying -Xs or -Xt to cause the compiler to evaluate float expressions as single precision.
(x86) Causes the compiler to convert the value of a floating-point expression or function to the type on the left-hand side of an assignment, when that expression or function is assigned to a variable, or when the expression is cast to a shorter floating-point type, rather than leaving the value in a register. Due to rounding and truncation, the results might be different from those that are generated from the register value. This is the default mode.
Use the -nofstore flag to disable this option.
Sets the IEEE trapping mode in effect at startup but does not install a SIGFPE handler. You can use ieee_handler(3M) or fex_set_handling(3M) to simultaneously enable traps and install a SIGFPE handler. If you specify more than one value, the list is processed sequentially from left to right.
t can be one of the values listed in the following table.
|
Note that the no% prefix 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% prefix does not explicitly cause a particular trap to be disabled.
If you do not specify –ftrap, the compiler assumes –ftrap=%none.
Example: –ftrap=%all,no%inexact sets all traps except inexact.
If you compile one routine with -ftrap=t, you should compile all routines of the program with the same option to avoid 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. To enable the IEEE traps, use -ftrap=common.
Produces a shared object rather than a dynamically linked executable. This option is passed to ld(1), and cannot be used with the -dn option.
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.
If you are creating a shared object by specifying -G along with other compiler options that must be specified at both compile time and link time, make sure that those same options are also specified when you link with the resulting shared object.
When you create a shared object, all the 64–bit SPARC object files that are compiled with -m64 must also be compiled with an explicit -xcode value as documented in -xcode[=v].
Produces additional symbol table information for debugging with dbx(1) and the Performance Analyzer, analyzer(1).
If you specify -g, 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 specify -g and the optimization level is -xO4, the compiler provides best-effort symbolic information with full optimization.
Compile with the -g option to use the full capabilities of the Performance Analyzer. 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 the Performance Analyzer manual 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.
-g is implemented as a macro that expands to various other, more primitive, options. See -xdebuginfo for the details of the expansions.
Produce standard debugging information.
Do not produce any debugging information. This is the default.
Produce file and line number as well as simple parameter information that is considered crucial during post-mortem debugging.
Same as -g.
Produce additional debugging information, which currently consists only of macro definition information. This added information can result in an increase in the size of the debug information in the resulting .o and executable when compared to using only -g.
For more information about debugging, see the Debugging a Program With dbx manual.
Prints to standard error, one per line, the path name of each file included during the current compilation. The display is indented to show which files are included by other files.
In the following example, the program sample.c includes the files stdio.h and math.h. math.h includes the file floatingpoint.h, which itself includes functions that use sys/ieeefp.h.
% cc -H sample.c /usr/include/stdio.h /usr/include/math.h /usr/include/floatingpoint.h /usr/include/sys/ieeefp.h
Assigns a name to a shared dynamic library as a way to have different versions of a library. name should be the same as the file name provided with the -o option. The space between -h and name is optional.
The linker assigns the specified name to the library and 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.
When the runtime linker loads the library into an executable file, it copies the intrinsic name from the library file into the executable's, list of needed shared library files. Every executable has such a list. If no intrinsic name of a shared library is provided, the linker copies the path of the shared library file instead.
-I dir adds dir to the list of directories that are searched for #include files with relative file names prior to /usr/include, that is, those directory paths not beginning with a / (slash).
Directories for multiple -I options are searched in the order specified.
For more information on the search pattern of the compiler, see Using the -I- Option to Change the Search Algorithm.
Passes the option to the linker to ignore any LD_LIBRARY_PATH or LD_LIBRARY_PATH_64 setting.
This option causes the compiler to treat filename as if it appears in the first line of a primary source file as a #include preprocessor directive. Consider the source file t.c:
main() { ... }
If you compile t.c with the command cc -include t.h t.c, the compilation proceeds as if the source file contains the following:
#include "t.h" main() { ... }
The compiler first searches for filename is the current working directory rather than the directory containing the main source file, as is the case when a file is explicitly included. For example, the following directory structure contains two header files with the same name, but at different locations:
foo/ t.c t.h bar/ u.c t.h
If your working directory is foo/bar and you compile with the command cc ../t.c -include t.h, the compiler includes t.h from foo/bar, not foo/ as would be the case with a #include directive from within the source file t.c.
If the compiler cannot find the file specified with –include in the current working directory, it searches the normal directory paths for the file. If you specify multiple –include options, the files are included in the order in which they appear on the command line.
(SPARC) Obsolete. You should not use this option. Use -xcode=pic32 instead.
For more information, see -xcode[=v]. For a complete list of obsolete options, see Obsolete Options.
(x86) -KPIC is identical to -Kpic.
(SPARC) Obsolete. You should not use this option. Use -xcode=pic13 instead. For more information, see -xcode[=v]. For a complete list of obsolete options, see Obsolete Options.
(x86) Produces 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.
Retains temporary files created during compilation instead of deleting them automatically.
Adds dir to the list of directories searched for libraries by ld(1). This option and its arguments are passed to ld(1).
Links with object library libname.so, or libname.a. The order of libraries in the command is important, as symbols are resolved from left to right.
This option must follow the sourcefile arguments.
Link with the Oracle Solaris Studio performance libraries.
Specifies the memory model for the compiled binary object.
Use –m32 to create 32-bit executables and shared libraries. Use –m64 to create 64-bit executables and shared libraries.
The ILP32 memory model (32-bit int, long, pointer data types) is the default on all Oracle Solaris platforms and on Linux platforms that are not 64-bit enabled. The LP64 memory model (64-bit long, pointer data types) is the default on Linux platforms that are 64-bit enabled. –m64 is permitted only on platforms that are enabled for the LP64 model.
Object files or libraries compiled with –m32 cannot be linked with object files or libraries compiled with–m64.
Modules that are compiled with –m32 |–m64 must also be linked with –m32 |–m64. For a complete list of compiler options that must be specified at both compile time and at link time, see Compile-Time and Link-Time Options
When compiling applications with large amounts of static data using –m64 on x86/x64 platforms, –xmodel=medium may also be required. Be aware that some Linux platforms do not support the medium model.
Note that in previous compiler releases, the memory model, ILP32 or LP64, was implied by the choice of the instruction set with –xarch. Starting with the Oracle Solaris Studio 12 compilers, this default is no longer the case. On most platforms, just adding –m64 to the command line is sufficient to create 64-bit objects.
On Oracle Solaris, –m32 is the default. On Linux systems supporting 64-bit programs, –m64 –xarch=sse2 is the default.
See also the description of –xarch.
Removes duplicate strings from the .comment section of the object file. When you use the -mc flag, mcs -c is invoked.
(SPARC) Obsolete. You should not use this option. Use the -xmemalign=1i option instead. For more information, see -xmemalign=ab. For a complete list of obsolete options, see Obsolete Options.
(SPARC) Obsolete. You should not use this option. Use the –xmemalign=2i option instead. For more information, see -xmemalign=ab. For a complete list of obsolete options, see Obsolete Options.
-mr removes all strings from the .comment section. When you use this flag, mcs -d -a is invoked.
-mr,string removes all strings from the .comment section and inserts string in that section of the object file. If string contains embedded blanks, it must be enclosed in quotation marks. A null string results in an empty .comment section. This option is passed as -d -astring to mcs.
Use this option to compile and link multithreaded code using the Oracle Solaris threads or POSIX threads API. The –mt=yes option assures that libraries are linked in the appropriate order.
This option passes -D_REENTRANT to the preprocessor.
To use Oracle Solaris threads, include the thread.h header file and compile with the —mt=yes option. To use POSIX threads on Oracle Solaris platforms, include the pthread.h header file and compile with the —mt=yes option.
On Linux platforms, only the POSIX threads API is available. (libthread is not available on Linux platforms.) Consequently, —mt=yes on Linux platforms adds —lpthread instead of —lthread. To use POSIX threads on Linux platforms, compile with —mt.
Note that when compiling with —G, neither —lthread nor —lpthread are automatically included by —mt=yes. You will need to explicitly list these libraries when building a shared library.
The -xopenmp option and the -xautopar option include -mt=yes automatically.
If you compile with –mt=yes and link in a separate step, you must use the -mt=yes option in the link step as well as the compile step. If you compile and link one translation unit with –mt=yes, you must compile and link all units of the program with –mt=yes
-mt=yes is the default behavior of the compiler. If this behavior is not desired, compile with -mt=no.
The option —mt is equivalent to —mt=yes.
See also -xnolib, and the Oracle Solaris Multithreaded Programming Guide, and Linker and Libraries Guide
This option is a synonym for -xtarget=native.
(x86) Does not convert the value of a floating-point expression or function to the type on the left-hand side of an assignment when that expression or function is assigned to a variable or is cast to a shorter floating-point type. Instead, it leaves the value in a register. See also -fstore.
Use default optimization level -xO3. The -O macro expands to -xO3.
The -xO3 optimization level yields higher runtime performance. However, this may be inappropriate for programs that rely on all variables being automatically considered volatile. Typical programs that might have this assumption are device drivers and older multithreaded applications that implement their own synchronization primitives. The workaround is to compile with -xO2 instead of -O.
Names the output file filename, instead of the default a.out. filename cannot be the same as the input source file since the compiler will not overwrite a source file.
filename must have an appropriate suffix. When used with —c, filename specifies the target .o object file; with —G it specifies the target .so library file. This option and its argument are passed to the linker, ld.
Runs the source file through the C preprocessor only. It then puts the output in a file with a .i suffix. Unlike -E, this option does not include preprocessor-type line number information in the output. See also the -E option.
The option is now obsolete. Use -xpg instead.
Strict conformance with errors/warnings for non-ANSI constructs. The -std flag can be used to specify which ANSI standard is in effect. The -Xc, -Xa, -Xt, -Xs, and -xc99 flags cannot be specified with the -pedantic flag. Doing so will result in an error being issued by the compiler.
When -pedantic is not specified, the default is -pedantic=no.
-pedantic is equivalent to -pedantic=yes.
(x86) Saves copies of register-based function arguments in the stack.
When none is specified or if the -preserve_argvalues option is not specified on the command line, the compiler behaves as usual.
When simple is specified, up to six integer arguments are saved.
When complete is specified, the values of all function arguments in the stack trace are visible to the user in the proper order.
The values are not updated during the function lifetime on assignments to formal parameters.
Passes option to the compilation phase.
To pass multiple options, specify them in order as a comma-separated list. Options that are passed to components with -Qoption might be reordered. Options that the driver recognizes are kept in the correct order. Do not use -Qoption for options that the driver already recognizes.
phase can be one of the values in the following list.
Compiler
Code generator (SPARC)
Preprocessor
cc driver
Assembler
Interprocedural optimizer
Optimizer
Link editor (ld)
mcs — manipulate comment section of object file when —mc or —mr specified.
Postoptimizer
Compiler phase for lock_lint
Code generator (x86)
See also —Wc,arg, which provides equivalent functionality. —Qoption is provided for compatibility with other compilers.
Determines whether to emit identification information to the output file. -Qy is the default.
If -Qy is used, identification information about each invoked compilation tool is added to the .comment section of output files, which is accessible with mcs. This option can be useful for software administration.
-Qn suppresses this information.
Passes a colon-separated list of directories used to specify library search directories to the runtime linker. If present and not null, the directory list is recorded in the output object file and passed to the runtime linker.
If both LD_RUN_PATH and the -R option are specified, the -R option takes precedence.
Directs cc to produce an assembly source file but not to assemble or link the program. The assembler-language output is written to corresponding files suffixed .s.
Removes all symbolic debugging information from the output object file. This option cannot be specified with -g.
Passed to ld(1).
When used with -library=sunperf, -staticlib=sunperf will link statically with the Sun performance libraries. By default and when -library=no%sunperf is specified, -library=sunperf results in dynamic linking of the Sun performance libraries.
For compatibility with CC, %all and %none are also accepted values for -staticlib, where %all is equivalent to sunperf and %none is equivalent to no%sunperf.
C language standard selection flag.
value is defined as one of the following:
C source language accepted is that defined by the ISO C90 standard.
C source language accepted is that defined by the ISO C99 standard.
C source language accepted is that defined by the ISO C11 standard.
The first default is c11, implying acceptance of the C source language as defined by ANSI C11 with extensions. There is no second default. Instead, specification of -std without a value will generate an error.
When any of the flags -Xc, -Xa, -Xt, or -xtransition are specified, the -std first default is not in effect and the compiler defaults to -xc99=all,no_lib. When -Xs is specified, the first default is not in effect and the compiler defaults to -xc99=none. When -xc99 is specified, the -std first default is not in effect and the compiler is as specified by -xc99.
The -Xc, -Xa, -Xt, -Xs, and -xc99 flags cannot be used if the -std flag has been specified. Doing so will result in an error being issued by the compiler.
If you compile and link in separate steps you must use the same values for -std flag in both steps.
Defines the directory for temporary files.
This option sets the path name of the directory for storing the temporary files which are generated during the compilation process. The compiler gives precedence to the value set by –temp over the value of TMPDIR.
–keeptmp
Issues a stack trace if a severe error occurs in execution.
The -traceback option causes the executable to issue a stack trace to stderr, dump core, and exit if certain signals are generated by the program. If multiple threads generate a signal, a stack trace will only be produced for the first one.
To use traceback, add the -traceback option to the compiler command line when linking. The option is also accepted at compile time but is ignored unless an executable binary is generated. Using -traceback with -G to create a shared library is an error.
|
If the option is not specified, the default is -traceback=%none
-traceback alone, without a = sign, implies -traceback=common
If you don't want the core dump, set the coredumpsize limit to zero as follows:
% limit coredumpsize 0
The -traceback option has no effect on runtime performance.
Undefines the preprocessor symbol name. This option removes any initial definition of the preprocessor symbol name created by -D on the same command line, including the ones placed there by the command-line driver.
-U has no effect on any preprocessor directives in source files. You can give multiple -U options on the command line.
If the same name is specified for both -D and -U on the command line, name is undefined, regardless of the order in which the options appear. In the following example, -U undefines __sun:
cc -U__sun text.c
Preprocessor statements of the following form in test.c will not take effect because __sun is undefined.
#ifdef(__sun)
See -Dname[(arg[,arg])][=expansion] for a list of predefined symbols.
Directs cc to print the name and version ID of each component as the compiler executes.
Directs the compiler to perform stricter semantic checks and to enable other lint-like checks. For example, the following code compiles and executes without problem.
#include <stdio.h> main(void) { printf("Hello World.\n"); }
With the -v option it still compiles. However, the compiler displays this warning:
"hello.c", line 5: warning: function has no return statement: main
-v does not give all the warnings that lint(1) does. You can see the difference by running the above example through lint.
Passes the argument arg to a specified component c. See Table 1–1 for a list of components.
Arguments must be separated from the preceding only by a comma. All -W arguments are passed after the rest of the command-line arguments. To include a comma as part of an argument, use the escape character \ (backslash) immediately before the comma. All -W arguments are passed after the regular command-line arguments.
For example, -Wa,-o,objfile passes -o and objfile to the assembler in that order. Also, -Wl,-I,name causes the linking phase to override the default name of the dynamic linker, /usr/lib/ld.so.1.
The order in which the arguments are passed to a tool with respect to the other specified command line options might change an subsequent compiler releases.
The possible values for c are listed in the following table
|
Note that you cannot use -Wd to pass cc options to the c compiler.
Suppresses compiler warning messages.
This option overrides the error_messages pragma.
(Obsolete) The -Xs option will be removed in a future release. It is recommended that C code that requires -Xs to build and compile correctly be migrated to conform with at least the C99 dialect of the ISO C standard, that is, compilable with -std=c99.
The -Xc, -Xa, -Xt, and -Xs flags cannot be used if the -std or -xlang flag has been specified.
When not using the -std flag, the -X (note uppercase X) options specify varying degrees of compliance to the 1990 and 1999 ISO C standard. The value of -xc99 affects which version of the ISO C standard the -X option applies. The -xc99 option defaults to -xc99=all which supports the 1999 ISO/IEC C standard. -xc99=none supports the 1990 ISO/IEC C standard. See D.1 for a discussion of supported 1999 ISO/IEC features. See Appendix H for a discussion of differences between ISO/IEC C and K&R C.
The default mode of the compiler is -std=c11 without the -pedantic flag. If the -xc99 flag has been specified or is in effect, then -Xa is the default mode of the compiler .
-Xc
(c = conformance) Issues errors and warnings for programs that use non-ISO C constructs. This option is strictly conformant ISO C without K&R C compatibility extensions. The predefined macro __STDC__ has a value of 1 with the–Xc option.
–Xa
ISO C plus K&R C compatibility extensions with semantic changes required by ISO C. Where K&R C and ISO C specify different semantics for the same construct, the compiler uses the ISO C interpretation. If the -Xa option is used in conjunction with the -xtransition option, the compiler issues warnings about the different semantics. The predefined macro __STDC__has a value of –0 with the–Xa option.
-Xt
(t = transition) This option uses ISO C plus K&R C compatibility extensions without semantic changes required by ISO C. Where K&R C and ISO C specify different semantics for the same construct, the compiler uses the K&R C interpretation. If you use the -Xt option in conjunction with the -xtransition option, the compiler issues warnings about the different semantics. The predefined macro __STDC__ has a value of 0 with the -Xt option.
-Xs
(s = K&R C) Attempts to warn about all language constructs that have differing behavior between ISO C and K&R C. The compiler language includes all features compatible with K&R C. This option invokes cpp for preprocessing. __STDC__ is not defined in this mode.
(x86) Obsolete. You should not use this option. Use -xchip=generic instead. For a complete list of obsolete options, see Obsolete Options.
(x86) Obsolete. You should not use this option. Use -xchip=generic instead. For a complete list of obsolete options, see Obsolete Options.
Pass arg to linker ld(1). Equivalent to —z arg
(Solaris x86/x64 only) The -xaddr32=yes compilation flag restricts the resulting executable or shared object to a 32-bit address space.
An executable that is compiled in this manner results in the creation of a process that is restricted to a 32-bit address space.
When -xaddr32=no is specified a usual 64 bit binary is produced.
If the -xaddr32 option is not specified, -xaddr32=no is assumed.
If only -xaddr32 is specified -xaddr32=yes is assumed.
This option is only applicable to -m64 compilations and only on Oracle Solaris platforms supporting SF1_SUNW_ADDR32 software capability. Because Linux kernels do not support address space limitation, this option is not available on Linux.
When linking, if a single object file was compiled with -xaddr32=yes, the whole output file is assumed to be compiled with -xaddr32=yes.
A shared object that is restricted to a 32-bit address space must be loaded by a process that executes within a restricted 32-bit mode address space.
For more information refer to the SF1_SUNW_ADDR32 software capabilities definition, described in the Linker and Libraries Guide.
The compiler uses the -xalias_level option to determine what assumptions it can make in order to perform optimizations using type-based alias-analysis. This option places the indicated alias level into effect for the translation units being compiled.
If you do not specify the -xalias_level command, the compiler assumes -xalias_level=any. If you specify -xalias_level without a value, the default is -xalias_level=layout.
The -xalias_level option requires optimization level -xO3 or above. If optimization is set lower, a warning is issued and the -xalias_level option is ignored.
Remember that if you issue the -xalias_level option but you fail to adhere to all of the assumptions and restrictions about aliasing described for any of the alias levels, the behavior of your program is undefined.
Replace l with one of the terms in the following table.
(Obsolete) This option will be removed in a future release. Use -xprevise instead.
Produce a static analysis of the source code that can be viewed using the Oracle Solaris Studio Code Analyzer.
When compiling with —xanalyze=code and linking in a separate step, include —xanalyze=code also on the link step.
The default is —xanalyze=%none.
On Linux, -xanalyze=code needs to be specified along with -xannotate.
See the Oracle Solaris Studio Code Analyzer documentation for more information.
Create binaries that can later be used by the optimization and observability tools binopt(1), code-analyzer(1), discover(1), collect(1), and uncover(1).
The default on Oracle Solaris is -xannotate=yes. The default on Linux is -xannotate=no. Specifying -xannotate without a value is equivalent to -xannotate=yes.
For optimal use of the optimization and observability tools, -xannotate=yes must be in effect at both compile and link time. Compile and link with -xannotate=no to produce slightly smaller binaries and libraries when optimization and observability tools will not be used.
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. This option does not guarantee use of any target–specific instructions. However, use of this option could affect the portability of a binary program.
If you compile and link in separate steps, make sure you specify the same value for -xarch in both steps.
When specifying the _asm statement, or compiling with .il inline templates files that use architecture-specific instructions, it might be necessary to specify an appropriate -xarch value to avoid compilation errors.
The following table lists the -xarch keywords common to both SPARC and x86 platforms.
|
The following table describes the -xarch keywords on SPARC platforms.
|
Also note the following:
Object binary files (.o) compiled with generic, sparc, sparcvis2, sparcvis3, sparcfmaf, sparcima can be linked and can execute together but can only run on a processor supporting all the instruction sets linked.
For any particular choice, the generated executable might not run or might run much more slowly on legacy architectures. Also, because quad-precision (long double) floating-point instructions are not implemented in any of these instruction set architectures, the compiler does not use these instructions in the code it generates.
The following table lists the -xarch flags on x86 platforms.
|
If any part of a program is compiled or linked on an x86 platform with —m64, then all parts of the program must be compiled with one of these options as well. For details on the various Intel instruction set architectures (SSE, SSE2, SSE3, SSSE3, and so on) refer to the Intel 64 and IA-32 Architectures Software Developer Manuals at http://www.intel.com.
See also Special x86 Notes and Binary Compatibility Verification.
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=sparcvis -xchip=ultra2 -xcache=16/32/1:512/64/1. In the following command -xarch=generic overrides the -xarch=sparcvis that is set by the expansion of -xtarget=ultra2.
example% cc -xtarget=ultra2 -xarch=generic foo.c
If you use this option 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.
If you compile and link in separate steps, make sure you specify the same value for -xarch in both steps.
Enables automatic parallelization of loops. Does dependence analysis (analyze loops for inter-iteration data dependence) and loop restructuring. If optimization is not at -xO3 or higher, optimization is raised to -xO3 and a warning is issued.
Avoid-xautopar if you do your own thread management.
To achieve faster execution, this option requires a system with multiple hardware threads. Use the OMP_NUM_THREADS or PARALLEL environment variable to specify the number of threads you want to use. Refer to the OpenMP API User's Guide for information about these environment variables and their default values.
For best performance, the number of threads used to execute a parallel region should not exceed the number of hardware threads (or virtual processors) available on the machine. On Oracle Solaris systems, this number can be determined by using the psrinfo(1M) command. On Linux systems, this number can be determined by inspecting the file /proc/cpuinfo.
If you use-xautopar and compile and link in one step, then linking automatically includes the microtasking library (libmtsk.so) and the threads-safe C runtime library. If you use-xautopar and compile and link in separate steps, then you must also link with -xautopar. For a complete list of all compiler options that must be specified at both compile time and at link time, see Table A–2.
(SPARC) This option is now obsolete and will be removed in a future release of the compiler. See -xannotate[=yes|no]
Instructs the compiler to prepare the binary for later optimizations, transformations and analysis. This option may be used for building executables or shared objects. This option must be used with optimization level -xO1 or higher to be effective. There is a modest increase in size of the binary when built with this option.
If you compile in separate steps, -xbinopt must appear on both compile and link steps:
example% cc -c -xO1 -xbinopt=prepare a.c b.c example% cc -o myprog -xbinopt=prepare a.o
If some source code is not available for compilation, this option may still be used to compile the remainder of the code. It should then be used in the link step that creates the final binary. In such a situation, only the code compiled with this option can be optimized, transformed or analyzed.
Compiling with -xbinopt=prepare and -g increases the size of the executable by including debugging information. The default is -xbinopt=off.
For more information, see the binopt(1) man page.
Use the -xbuiltinoption to improve the optimization of code that calls standard library functions. Many standard library functions, such as the ones defined in math.h and stdio.h, are commonly used by various programs. The -xbuiltin option enables the compiler to substitute intrinsic functions or inline system functions where profitable for performance. See the er_src(1) man page for an explanation of how to read compiler commentary in object files to determine the functions for which the compiler actually makes a substitution.
Note that these substitutions can cause the setting of errno to become unreliable. If your program depends on the value of errno, avoid this option. See also Preserving the Value of errno.
-xbuiltin=%default only inlines functions that do not set errno. The value of errno is always correct at any optimization level, and can be checked reliably. With -xbuiltin=%default at -xO3 or lower, the compiler will determine which calls are profitable to inline, and not inline others. The -xbuiltin=%none option turns off all substitutions of library functions.
If you do not specify -xbuiltin, the default is -xbuiltin=%default when compiling with an optimization level -xO1 and higher, and -xbuiltin=%none at -xO0. If you specify -xbuiltin without an argument, the default is -xbuiltin=%all and the compiler substitutes intrinsics or inlines standard library functions much more aggressively.
If you compile with -fast, then -xbuiltin is set to %all.
When you specify -std=c89 and -xCC, the compiler accepts the C++-style comments. In particular, // can be used to indicate the start of a comment.
The -xc99 option controls compiler recognition of the implemented features from the C99 standard (ISO/IEC 9899:1999, Programming Language - C).
The following table lists accepted values for o. Multiple values can be separated by commas.
|
If you do not specify -xc99, the compiler defaults to -xc99=all,no_lib. If you specify -xc99 without any values, the option is set to-xc99=all.
The -xc99 flag cannot be used if the -std or -xlang flag has been specified.
Defines cache properties for use by the optimizer . This option does not guarantee that any particular cache property is used.
An optional property, [/ti], sets the number of threads that can share the cache. If you do not specify a value for t, the default is 1.
c must be one of the following:
generic
native
s1/l1/a1[/t1]
s1/l1/a1[/t1]:s2/l2/a2[/t2]
s1/l1/a1[/t1]:s2/l2/a2[/t2]:s3/l3/a3[/t3]
The s/l/a/t properties are defined as follows:
The size of the data cache at level i, in kilobytes
The line size of the data cache at level i, in bytes
The associativity of the data cache at level i
The number of hardware threads sharing the cache at level i
The following table lists the-xcache values.
|
Example:-xcache=16/32/4:1024/32/1 specifies the following:
Level 1 cache with:
16K bytes
32 bytes line size
Four–way associativity
Level 2 cache with:
1024 bytes
32 bytes line size
Direct mapping associativity
(SPARC) Obsolete. You should not use this option. Compiling with this option generates code that runs slower on current SPARC platforms. Use -O instead and take advantage of compiler defaults for -xarch, -xchip, and -xcache.
The option is provided solely for the purpose of easing the migration of code from systems where the char type is defined as unsigned. Unless you are migrating from such a system, do not use this option. Only code that relies on the sign of a char type needs to be rewritten to explicitly specify signed or unsigned.
The following table lists the accepted values for o:
|
If you do not specify -xchar, the compiler assumes -xchar=s.
If you specify -xchar but do not specify a value, the compiler assumes -xchar=s.
The -xchar option changes the range of values for the type char only for code compiled with -xchar. This option does not change the range of values for type char in any system routine or header file. In particular, the value of CHAR_MAX and CHAR_MIN, as defined by limits.h, do not change when this option is specified. Therefore, CHAR_MAX and CHAR_MIN no longer represent the range of values encodable in a plain char.
If you use -xchar, be particularly careful when you compare a char against a predefined system macro because the value in the macro may be signed. This situation is most common for any routine that returns an error code that is accessed through a macro. Error codes are typically negative values so when you compare a char against the value from such a macro, the result is always false. A negative number can never be equal to any value of an unsigned type.
Do not use -xchar to compile routines for any interface exported through a library. The ABIs for all target platforms of Oracle Solaris Studio specify type char as signed, and system libraries behave accordingly. The effect of making char unsigned has not been extensively tested with system libraries. Instead of using this option, modify your code so that it does not depend on whether type char is signed or unsigned. The sign of type char varies among compilers and operating systems.
Produce an integer constant by placing the characters of a multicharacter character-constant in the specified byte order. Use one of the following values for o:
low: Places the characters of a multicharacter character-constant in low-to-high byte order.
high: Places the characters of a multicharacter character-constant in high-to-low byte order.
default: Places the characters of a multicharacter character-constant in an order determined by the compilation mode (-Xv). For more information, see Character Constants and -X[c|a|t|s].
Adds runtime checks for stack overflow and initializes local variables.
The following table lists values for o.
|
If you do not specify -xcheck, the compiler defaults to-xcheck=%none. If you specify -xcheck without any arguments, the compiler defaults to-xcheck=%all.
The -xcheck option does not accumulate on the command line. The compiler sets the flag in accordance with the last occurrence of the command. Thus, to enable both stack overflow diagnosis an local variable initialization, use the following option:
cc -xcheck=stkovf:diagnose,init_local ...
With -xcheck=init_local, the compiler initializes local variables declared without an initializer to a predefined value as shown in the following table. (Note that these values might change and should not be relied upon.)
|
Local variables declared for use with the computed goto, which are simple void * pointers, will be initialized according to the description for pointers in the table.
The following local variable types are never initialized: const qualified, register, label numbers for computed gotos, local labels.
Fields in a struct that are basic types are initialized as described in the table, as is the first declared pointer or float field in a union, to maximize the likelihood that an uninitialized reference generates a visible error.
Array elements are also initialized as described in the table.
Nested struct, union, and array fields are initialized as described in the table except for the following cases: a struct containing bit-fields, a union without a pointer or float field, or an array of types that cannot be fully initialized. These exceptions will be initialized with the value used for local variables of type double.
Specifies the target processor for use by the optimizer.
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.
This option specifies timing properties by specifying the target processor. Some effects are:
The ordering of instructions, that is, scheduling
The way the compiler uses branches
The instructions to use in cases where semantically equivalent alternatives are available
The following table lists the -xchip values for c for SPARC platforms:
|
The following table lists the -xchip values for the x86 platforms:
|
(SPARC) Specify code address space.
The following table lists the values for v.
|
The default is -xcode=abs32 for 32–bit architectures. The default for 64–bit architectures is-xcode=abs44.
When building shared dynamic libraries, the default -xcode values of abs44 and abs32 will not work with 64–bit architectures. Specify -xcode=pic13 or -xcode=pic32 instead. Two nominal performance costs with -xcode=pic13 and -xcode=pic32 on SPARC are:.
A routine compiled with either -xcode=pic13 or -xcode=pic32 executes a few extra instructions upon entry to set a register to point at a table (_GLOBAL_OFFSET_TABLE_) used for accessing a shared library’s global or static variables.
Each access to a global or static variable involves an extra indirect memory reference through _GLOBAL_OFFSET_TABLE_. If the compilation includes -xcode=pic32, there are two additional instructions per global and static memory reference.
When considering these costs, remember that the use of -xcode=pic13 and -xcode=pic32 can significantly reduce system memory requirements due to the effect of library code sharing. Every page of code in a shared library compiled -xcode=pic13 or -xcode=pic32 can be shared by every process that uses the library. If a page of code in a shared library contains even a single non-pic (that is, absolute) memory reference, the page becomes nonsharable, and a copy of the page must be created each time a program using the library is executed.
The easiest way to tell whether a .o file has been compiled with -xcode=pic13 or -xcode=pic32 is by using the nm command:
% nm file.o | grep _GLOBAL_OFFSET_TABLE_ U _GLOBAL_OFFSET_TABLE_
A .o file containing position-independent code contains an unresolved external reference to _GLOBAL_OFFSET_TABLE_, as indicated by the letter U.
To determine whether to use -xcode=pic13 or -xcode=pic32, check the size of the Global Offset Table (GOT) by using elfdump -c looking for the section header sh_name: .got. The sh_size value is the size of the GOT. If the GOT is less than 8,192 bytes, specify -xcode=pic13. Otherwise specify -xcode=pic32.See the elfdump(1) man page for more information.
Follow these guidelines to determine how you should use -xcode:
If you are building an executable, do not use -xcode=pic13 or -xcode=pic32.
If you are building an archive library only for linking into executables, do not use -xcode=pic13 or -xcode=pic32.
If you are building a shared library, start with -xcode=pic13 and, once the GOT size exceeds 8,192 bytes, use -xcode=pic32.
If you are building an archive library for linking into shared libraries, use -xcode=pic32.
Obsolete, do not use. Use –xipo instead. -xcrossfile is an alias for —xipo=1.
Allows the C compiler to accept source code written in locales that do not conform to the ISO C source character code requirements. These locales include ja_JP.PCK.
The compiler translation phases required to handle such locales may result in significantly longer compilation times. You should only use this option when you compile source files that contain source characters from one of these locales.
The compiler does not recognize source code written in locales that do not conform to the ISO C source character code requirements unless you specify -xcsi.
Specify -xdebugformat=dwarf if you maintain software which reads debugging information in the DWARF format. This option causes the compiler to generate debugging information by using the DWARF standard format and is the default.
|
If you do not specify -xdebugformat, the compiler assumes -xdebugformat=dwarf. This option requires an argument.
This option affects the format of the data that is recorded with the -g option. Some small amount of debugging information is recorded even without -g, and the format of that information is also controlled with this option. Therefore, -xdebugformat has an effect even when -g is not used.
The dbx and Performance Analyzer software understand both STABS and DWARF format so using this option does not have any effect on the functionality of either tool.
See the dumpstabs(1) and dwarfdump(1) man pages for more information.
Control how much debugging and observability information is emitted.
The term tagtype refers to tagged types: structs, unions, enums, and classes.
The following list contains the possible values for suboptions a. The prefix no% applied to a suboption disables that suboption. The default is -xdebuginfo=%none. Specifying -xdebuginfo without a suboption is forbidden.
No debugging information is generated. This is the default.
Emit line number and file information.
Emit location list info for parameters. Emit full type information for scalar values (for example, int, char *) and type names but not full definitions of tagtypes.
Emit location list information for lexically global and local variables, including file and function statics but excluding class statics and externs. Emit full type information for scalar values such as int and char * and type names but not full definitions of tagtypes.
Emit information for function and variable declarations, member functions, and static data members in class declarations.
Emit full type definitions of tagtypes referenced from param and variable datasets, as well as template definitions.
Emit macro information.
Emit DWARF codetags (also known as Stabs N_PATCH). This is information regarding bitfields, structure copy, and spills used by RTC and discover.
Generate information critical to hardware counter profiling. This information includes ldst_map, a mapping from ld/st instructions to the symbol table entry being referenced, and branch_target table of branch-target addresses used to verify that backtracking did not cross a branch-target. See -xhwcprof for more information.
These are macros which expand to combinations of -xdebuginfo and other options as follows:
-g = -g2 -gnone = -xdebuginfo=%none -xglobalize=no -xpatchpadding=fix -xkeep_unref=no%funcs,no%vars -g1 = -xdebuginfo=line,param,codetag -xglobalize=no -xpatchpadding=fix -xkeep_unref=no%funcs,no%vars -g2 = -xdebuginfo=line,param,decl,variable,tagtype,codetag -xglobalize=yes -xpatchpadding=fix -xkeep_unref=funcs,vars -g3 = -xdebuginfo=line,param,decl,variable,tagtype,codetag,macro -xglobalize=yes -xpatchpadding=fix -xkeep_unref=funcs,vars
Analyzes loops for interiteration data dependencies and does loop restructuring, including loop interchange, loop fusion, and scalar replacement.
-xdepend defaults to -xdepend=on for all optimization levels -xO3 and above. Specifying an explicit setting of -xdepend overrides any default setting.
Specifying -xdepend without an argument is equivalent to -xdepend=yes.
Dependency analysis can help on single-processor systems. However, if you use -xdepend on single-processor systems, you should not also specify -xautopar because the -xdepend optimization will be done for a multiprocessor system.
This option is a macro for -###.
Use this option when you want to see how macros are behaving in your program. This option provides information such as macro defines, undefines, and instances of usage. It prints output to the standard error (stderr), based on the order in which macros are processed. The -xdumpmacros option is in effect through the end of the file or until it is overridden by the dumpmacros or end_dumpmacros pragma. See dumpmacros.
The following table lists the valid arguments for value. The prefix no% disables the associated value.
|
The option values accumulate, so specifying -xdumpmacros=sys -xdumpmacros=undefs has the same effect as -xdumpmacros=undefs,sys.
Specifying -xdumpmacros without any arguments defaults to -xdumpmacros=defs,undefs,sys. The default when not specifying -xdumpmacros is -xdumpmacros=%none.
If you use the option -xdumpmacros=use,no%loc, the name of each macro that is used is printed only once. However, if you want more detail, use the option -xdumpmacros=use,loc so the location and macro name is printed every time a macro is used.
Consider the following file t.c:
example% cat t.c #ifdef FOO #undef FOO #define COMPUTE(a, b) a+b #else #define COMPUTE(a,b) a-b #endif int n = COMPUTE(5,2); int j = COMPUTE(7,1); #if COMPUTE(8,3) + NN + MM int k = 0; #endif
The following examples show the output for file t.c based on the defs, undefs, sys, and loc arguments.
example% cc -c -xdumpmacros -DFOO t.c #define __SunOS_5_9 1 #define __SUNPRO_C 0x512 #define unix 1 #define sun 1 #define sparc 1 #define __sparc 1 #define __unix 1 #define __sun 1 #define __BUILTIN_VA_ARG_INCR 1 #define __SVR4 1 #define __SUNPRO_CC_COMPAT 5 #define __SUN_PREFETCH 1 #define FOO 1 #undef FOO #define COMPUTE(a, b) a + b example% cc -c -xdumpmacros=defs,undefs,loc -DFOO -UBAR t.c command line: #define __SunOS_5_9 1 command line: #define __SUNPRO_C 0x512 command line: #define unix 1 command line: #define sun 1 command line: #define sparc 1 command line: #define __sparc 1 command line: #define __unix 1 command line: #define __sun 1 command line: #define __BUILTIN_VA_ARG_INCR 1 command line: #define __SVR4 1 command line: #define __SUN_PREFETCH 1 command line: #define FOO 1 command line: #undef BAR t.c, line 2: #undef FOO t.c, line 3: #define COMPUTE(a, b) a + b
The following examples show how the use, loc, and conds arguments report macro behavior in file t.c:
example% cc -c -xdumpmacros=use t.c used macro COMPUTE example% cc -c -xdumpmacros=use,loc t.c t.c, line 7: used macro COMPUTE t.c, line 8: used macro COMPUTE example% cc -c -xdumpmacros=use,conds t.c used macro FOO used macro COMPUTE used macro NN used macro MM example% cc -c -xdumpmacros=use,conds,loc t.c t.c, line 1: used macro FOO t.c, line 7: used macro COMPUTE t.c, line 8: used macro COMPUTE t.c, line 9: used macro COMPUTE t.c, line 9: used macro NN t.c, line 9: used macro MM
Consider the file y.c:
example% cat y.c #define X 1 #define Y X #define Z Y int a = Z;
The following example shows the output from -xdumpmacros=use,loc based on the macros in y.c:
example% cc -c -xdumpmacros=use,loc y.c y.c, line 4: used macro Z y.c, line 4: used macro Y y.c, line 4: used macro X
Pragma dumpmacros/end_dumpmacros overrides the scope of the -xdumpmacros command-line option.
Performs syntax and semantic checking on the source file but does not produce any object or executable code.
Enables optimal reordering of functions and variables by the linker.
This option instructs the compiler to place functions or data variables into separate section fragments, which enables the linker, using directions in a mapfile specified by the linker’s -M option, to reorder these sections to optimize program performance. This optimization is most effective when page-fault time constitutes a significant fraction of program runtime.
Reordering of variables can help solve the following problems that negatively affect runtime performance:
Cache and page contention caused by unrelated variables that are near each other in memory.
Unnecessarily large work-set size as a result of related variables that are not near each other in memory.
Unnecessarily large work-set size as a result of unused copies of weak variables that decrease the effective data density.
Reordering variables and functions for optimal performance requires the following operations:
Compiling and linking with -xF.
Following the instructions about generating mapfiles for functions or for data in the Oracle Solaris Studio Performance Analyzer manual and Oracle Solaris Linker and Libraries Guide.
Relinking with the new mapfile by using the linker’s -M option.
Re-executing under the Analyzer to verify improvement.
The following table lists the values for v.
|
Precede the values (other than %all and %none) with no% to disable the suboption. For example no%func.
If you do not specify -xF, the default is -xF=%none. If you specify -xF without any arguments, the default is -xF=%none,func.
Using -xF=lcldata inhibits some address calculation optimizations, so you should use this flag only when it is experimentally justified.
See the analyzer(1), and ld(1) man pages.
Control globalization of file static variables but not functions.
Globalization is a technique needed by fix and continue and interprocedural optimization whereby file static symbols are promoted to global while a prefix is added to the name to keep identically named symbols distinct.
The default is -xglobalize=no. Specifying -xglobalize is equivalent to specifying -xglobalize=yes.
See -xpatchpadding.
-xipo requires globalization as well and will override -xglobalize.
Displays online help information.
-xhelp=flags displays a summary of the compiler options.
(SPARC) Enables compiler support for hardware counter-based profiling.
When -xhwcprof is enabled, the compiler generates information that helps tools associate profiled load and store instructions with the data-types and structure members (in conjunction with symbolic information produced with -g to which they refer. It associates profile data with the data space of the target rather than the instruction space. It provides insight into behavior that is not easily obtained from only instruction profiling.
You can compile a specified set of object files with -xhwcprof. However, -xhwcprof is most useful when applied to all object files in the application, identifying and correlating all memory references distributed in the application’s object files.
If you are compiling and linking in separate steps, use -xhwcprof at link time as well. Future extensions to -xhwcprof might require its use at link time. For a complete list of all compiler options that must be specified at both compile time and at link time, see Table A–2.
An instance of -xhwcprof=enable or -xhwcprof=disable overrides all previous instances of -xhwcprof in the same command line.
-xhwcprof is disabled by default. Specifying -xhwcprof without any arguments is the equivalent to -xhwcprof=enable.
-xhwcprof requires that optimization be enabled and that the debug data format be set to DWARF (-xdebugformat=dwarf), which is the default with current Oracle Solaris Studio compilers. The occurrence of -xhwcprof and -xdebugformat=stabs on the same command line is not permitted.
-xhwcprof uses -xdebuginfo to automatically enable the minimum amount of debugging information it needs, so -g is not required.
The combination of -xhwcprof and -g increases compiler temporary file storage requirements by more than the sum of the increases due to -xhwcprof and -g specified alone.
-xhwcprof is implemented as a macro that expands to various other, more primitive, options as follows:
-xhwcprof -xdebuginfo=hwcprof,tagtype,line -xhwcprof=enable -xdebuginfo=hwcprof,tagtype,line -xhwcprof=disable -xdebuginfo=no%hwcprof,no%tagtype,no%line
The following command compiles example.c and specifies support for hardware counter profiling and symbolic analysis of data types and structure members using DWARF symbols:
example% cc -c -O -xhwcprof -g -xdebugformat=dwarf example.c
For more information on hardware counter-based profiling, see the Oracle Solaris Studio Performance Analyzer manual.
The format of the list for -xinline is as follows: [{%auto,func_name,no%func_name}[,{%auto,func_name,no%func_name}]...]
-xinline tries to inline only those functions specified in the optional list. The list is either empty, or contains a comma-separated list of func_name, no%func_name, or %auto, where func_name is a function name. -xinline only has an effect at –xO3 or higher.
|
The list of values accumulates from left to right. For a specification of -xinline=%auto,no%foo the compiler attempts to inline all functions except foo. For a specification of -xinline=%bar,%myfunc,no%bar the compiler only tries to inline myfunc.
When you compile with optimization set at -xO4 or above, the compiler normally tries to inline all references to functions defined in the source file. You can restrict the set of functions the compiler attempts to inline by specifying the -xinline option. Specifying only -xinline= without naming any functions or %auto indicates that none of the routines in the source files are to be inlined. If you specify func_name and no%func_name without specifying %auto, the compiler only attempts to inline those functions specified in the list. If %auto is specified in the list of values with the -xinline option at optimization level set at -xO4 or above, the compiler attempts to inline all functions that are not explicitly excluded by no%func_name.
A function is not inlined if any of the following conditions apply. No warning is issued.
Optimization is less than -xO3.
The routine cannot be found.
Inlining the routine does not look practicable to the optimizer.
The source for the routine is not in the file being compiled (however, see -xipo).
If you specify multiple -xinline options on the command line, they do not accumulate. The last -xinline on the command line specifies the functions that the compiler attempts to inline.
See also -xldscope.
Use this option to manually change the heuristics used by the compiler for deciding when to inline a function call.
This option only has an effect at -O3 or higher. The following sub-options have an effect only at -O4 or higher when automatic inlining is on.
In the following sub-options n must be a positive integer; a can be one of the following:
|
If -xinline_param=default is specified, the compiler will set all the values of the subopitons to the default values.
If the option is not specified, the default is -xinline_param=default.
The list of values and options accumulate from left to right. So for a specification of -xinline_param=max_inst_hard:30,..,max_inst_hard:50, the value max_inst_hard:50 will be passed to the compiler.
If multiple -xinline_param options are specified on the command line, the list of sub-options likewise accumulate from left to right. For example, the effect of
-xinline_param=max_inst_hard:50,min_counter:70 ... -xinline_param=max_growth:100,max_inst_hard:100
will be the same as that of
-xinline_param=max_inst_hard:100,min_counter:70,max_growth:100
This option generates a report written to standard output on the inlining of functions by the compiler. The type of report depends on the value of n, which must be 0, 1, or 2.
No report is generated.
A summary report of default values of inlining parameters is generated.
A detailed report of inlining messages is generated, showing which callsites are inlined and which are not, with a short reason for not inlining a callsite. In some cases, this report will include suggested values for -xinline_param that can be used to inline a callsite that is not inlined.
When -xinline_report is not specified, the default value for n is 0. When -xinline_report is specified without =n, the default value is 1.
When -xlinkopt is present, the inlining messages about the callsites that are not inlined might not be accurate.
Specify this option to compile and instrument your program for analysis by the Thread Analyzer. For more information on the Thread Analyzer, see the tha(1) man page for details.
You can then use the Performance Analyzer to run the instrumented program with collect –r races to create a data-race-detection experiment. If you run the instrumented code stand-alone, it runs more slowly.
You can specify –xinstrument=no%datarace to turn off preparation of source code for the thread analyzer. This is the default.
You must specify –xinstrument= with an argument.
If you compile and link in separate steps, you must specify –xinstrument=datarace in both the compilation and linking steps.
This option defines the preprocessor token __THA_NOTIFY. You can specify #ifdef __THA_NOTIFY to guard calls to libtha(3) routines.
This option also sets –g.
Replace a with 0, 1, or 2. -xipo without any arguments is equivalent -xipo=1. -xipo=0 is the default setting and disables -xipo. With -xipo=1, the compiler performs inlining across all source files.
With -xipo=2, the compiler performs interprocedural aliasing analysis as well as optimizations of memory allocation and layout to improve cache performance.
The compiler performs partial-program optimizations by invoking an interprocedural analysis component. It performs optimizations across all object files in the link step, and is not limited to just the source files of the compile command. However, whole-program optimizations performed with -xipo do not include assembly (.s) source files.
You must specify -xipo both at compile time and at link time. For a complete list of all compiler options that must be specified at both compile time and at link time, see Table A–2.
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 is due to the additional optimizations performed. The object files created in the compilation steps have additional analysis information compiled within them to permit crossfile optimizations to take place at the link step.
If you have .o files compiled with the –xipo option from different compiler versions, mixing these files can result in failure with an error message about "IR version mismatch". When using the –xipo option, all the files should be compiled with the same version of the compiler.
-xipo 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.
Analysis and optimization is limited to the object files compiled with -xipo, and does not extend to object files or libraries.
-xipo is multiphased, so you need to specify -xipo for each step if you compile and link in separate steps.
Other important information about -xipo:
It requires an optimization level of at least -xO4.
Objects that are compiled without -xipo can be linked freely with objects that are compiled with -xipo.
In this example, compilation and linking occur in a single step:
cc -xipo -xO4 -o prog part1.c part2.c part3.c
The optimizer performs crossfile inlining across all three source files. This process is done in the final link step, so the compilation of the source files need not all take place in a single compilation. It could take place over a number of separate compilations, each specifying -xipo.
In this example, compilation and linking occur in separate steps:
cc -xipo -xO4 -c part1.c part2.c cc -xipo -xO4 -c part3.c cc -xipo -xO4 -o prog part1.o part2.o part3.o
A restriction is that libraries, even if compiled with -xipo, do not participate in crossfile interprocedural analysis, as shown in the following example:
cc -xipo -xO4 one.c two.c three.c ar -r mylib.a one.o two.o three.o ... cc -xipo -xO4 -o myprog main.c four.c mylib.a
In this example, interprocedural optimizations are performed between one.c, two.c and three.c, and between main.c and four.c, but not between main.c or four.c and the routines on mylib.a. (The first compilation might generate warnings about undefined symbols, but the interprocedural optimizations are performed because it is a compile and link step.)
The compiler tries to perform whole-program analysis and optimizations as it works with the set of object files in the link step. The compiler makes the following two assumptions for any function (or subroutine) foo() defined in this set of object files:
foo() is not called explicitly by another routine that is defined outside this set of object files at runtime.
The calls to foo() from any routine in the set of object files are not interposed upon by a different version of foo() defined outside this set of object files.
Do not compile with either -xipo=1 or -xipo=2 if assumption 2 is not true.
As an example, consider interposing on the function malloc() with your own version and compiling with -xipo=2. Consequently, all the functions in any library that reference malloc() that are linked with your code have to be compiled with -xipo=2 also and their object files need to participate in the link step. Because this process might not be possible for system libraries, do not compile your version of malloc() with -xipo=2.
As another example, suppose that you build a shared library with two external calls, foo() and bar() inside two different source files. Furthermore, suppose that bar() calls foo(). If foo() could be interposed at runtime, then do not compile the source file for foo() or for bar() with -xipo=1 or -xipo=2. Otherwise, foo() could be inlined into bar(), which could cause incorrect results.
The -xipo_archive option enables the compiler to optimize object files that are passed to the linker with object files that were compiled with -xipo and that reside in the archive library (.a) before producing an executable. Any object files contained in the library that were optimized during the compilation are replaced with their optimized version.
The following table lists the values for a.
|
If you do not specify a setting for -xipo_archive, the compiler sets it to -xipo_archive=none.
You must specify –xipo_archive= with a value.
Building -xipo without -xipo_build involves two passes through the compiler—once when producing the object files, and then again later at link time when performing the cross file optimization. Setting -xipo_build reduces compile time by avoiding optimizations during the initial pass and optimizing only at link time. Optimization is not needed for the object files, as with -xipo it will be performed at link time. If unoptimized object files built with -xipo_build are linked without including -xipo to perform optimization, the application will fail to link with an unresolved symbol error.
The following example performs a fast build of .o files, followed by crossfile optimization at link time:
% cc -O -xipo -xipo_build -o code1.o -c code1.c % cc -O -xipo -xipo_build -o code2.o -c code2.c % cc -O -xipo -o a.out code1.o code2.o
The -xipo_build will turn off -O when creating the .o files, to build these quickly. Full -O optimization will be performed at link time as part of -xipo crossfile optimization.
The following example links without using -xipo.
% cc -O -o a.out code1.o code2.o
If either code1.o or code2.o were generated with -xipo_build, the result will be a link-time failure indicating the symbol __unoptimized_object_file is unresolved.
When building .o files separately, the default behavior is -xipo_build=no. However, when the executable or library is built in a single pass from source files, -xipo_build will be implicitly enabled. For example:
% cc -fast -xipo a.c b.c c.c
will implicitly enable -xipo_build=yes for the first passes that generate a.o, b.o, and c.o. Include the option -xipo_build=no to disable this behavior.
Disable or set interpretation of #pragma ivdep pragmas (ignore vector dependencies).
The ivdep pragmas tell a compiler to ignore some or all loop-carried dependences on array references that it finds in a loop for purposes of optimization. This enables a compiler to perform various loop optimizations such as microvectorization, distribution, software pipelining, and so on., which would not be otherwise possible. It is used in cases where the user knows either that the dependences do not matter or that they never occur in practice.
The interpretation of #pragma ivdep directives depend upon the value of the —xivdep option.
The following list gives the values for p and their meaning.
ignore assumed loop-carried vector dependences
ignore all loop-carried vector dependences
ignore assumed backward loop-carried vector dependences
ignore all backward loop-carried vector dependences
do not ignore any dependences (disables ivdep pragmas)
These interpretations are provided for compatibility with other vendor's interpretations of the ivdep pragma.
Compile with multiple processes. If this flag is not specified, the default behavior is -xjobs=auto.
Specify the -xjobs option to set how many processes the compiler creates to complete its work. This option can reduce the build time on a multi-cpu machine. Currently, -xjobs works only with the -xipo option. When you specify -xjobs=n, the interprocedural optimizer uses n as the maximum number of code generator instances it can invoke to compile different files.
Generally, a safe value for n is 1.5 multiplied by the number of available processors. Using a value that is many times the number of available processors can degrade performance because of context switching overheads among spawned jobs. Also, using a very high number can exhaust the limits of system resources such as swap space.
When -xjobs=auto is specified, the compiler will automatically choose the appropriate number of parallel jobs.
You must always specify -xjobs with a value. Otherwise, an error diagnostic is issued and compilation aborts.
If -xjobs is not specified, the default behavior is -xjobs=auto. This can be overridden by adding -xjobs=n to the command line. Multiple instances of -xjobs on the command line override each other until the right-most instance is reached.
The following example links with up to three parallel processes for -xipo:
% cc -xipo -xO4 -xjobs=3 t1.o t2.o t3.o
The following example links serially with a single process for -xipo:
% cc -xipo -xO4 -xjobs=1 t1.o t2.o t3.o
The following example links in parallel, with the compiler choosing the number of jobs for -xipo:
% cc -xipo -xO4 t1.o t2.o t3.o
Note that this is exactly the same behavior as when explicitly specifying -xjobs=auto:
% cc -xipo -xO4 -xjobs=auto t1.o t2.o t3.o
Keep definitions of unreferenced functions and variables. The no% prefix allows the compiler to potentially remove the definitions.
The default is no%funcs,no%vars. Specifying -xkeep_unref is equivalent to specifying -xkeep_unref=funcs,vars, meaning that -keep_unref keeps everything.
Prohibit stack related optimizations for the named functions (name).
Prohibit stack related optimizations for all the code.
Allow stack related optimizations for all the code.
This option is accumulative and can appear multiple times on the command line. For example, —xkeepframe=%all —xkeepframe=no%func1 indicates that the stack frame should be kept for all functions except func1. Also, —xkeepframe overrides —xregs=frameptr. For example, —xkeepframe=%all —xregs=frameptr indicates that the stack should be kept for all functions, but the optimizations for —xregs=frameptr would be ignored.
If not specified on the command line, the compiler assumes -xkeepframe=%none as the default. If specified but without a value, the compiler assumes -xkeepframe=%all
The -xlang flag can be used to override the default libc behavior as specified by the -std flag. language must be one of the following:
Specify runtime library behavior of libc to be in conformance with the C90 standard.
Specify runtime library behavior of libc be in conformance with the C99 standard.
Equivalent to c99. The runtime library behavior of libc for c99 and c11 are identical.
When -xlang is not specified, the default value is c99 when -std=c99 has been specified and c11 when -std=c11 has been specified. Otherwise the default value is c89.
The -Xc, -Xa, -Xt, -Xs, and -xc99 flags cannot be used if -xlang has been specified. Doing so will result in an error being issued by the compiler.
If you compile and link in separate steps you must use the same values for -xlang in both steps.
To determine which driver to use for mixed-language linking , use the following language hierarchy:
Use the CC command. See the C++ Uder's Guide for details.
Use the f95 command. See the Fortran User's Guide for details.
Use f95 -xlang=f77. See the Fortran User's Guide for details.
Use the cc command.
Specify the -xldscope option to change the default linker scoping for the definition of extern symbols. Changing the default can result in faster and safer shared libraries because the implementation is better hidden.
v must be one of the following:
|
If you do not specify -xldscope, the compiler assumes -xldscope=global. The compiler issues an error if you specify -xldscope without an argument. Multiple instances of this option on the command line override each other until the rightmost instance is reached.
If you intend to allow a client to override a function in a library, you must be sure that the function is not generated inline during the library build. The compiler inlines a function in the following situations:
You specify the function name with -xinline.
You compile at -xO4 or higher, in which case inlining can happen automatically.
You use the inline specifier.
You use the inline pragma.
You use cross-file optimization.
For example, suppose library ABC has a default allocator function that can be used by library clients, and is also used internally in the library:
void* ABC_allocator(size_t size) { return malloc(size); }
If you build the library at -xO4 or higher, the compiler inlines calls to ABC_allocator that occur in library components. If a library user attempts to replace ABC_allocator with a customized version, the replacement will not occur in library components that called ABC_allocator. The final program will include different versions of the function.
Library functions declared with the __hidden or __symbolic specifiers can be generated inline when building the library. These functions are not supposed to be overridden by users. For more information, see Linker Scoping Specifiers.
Library functions declared with the __global specifier should not be declared inline, and should be protected from inlining by use of the -xinline compiler option.
See also -xinline, -xO, -xipo, #pragma inline.
Forces IEEE 754 style return values for math routines in exceptional cases. In such cases, no exception message is printed, and you should not rely on errno.
Inlines some library routines for faster execution. This option selects the appropriate assembly language inline templates for the floating-point option and platform for your system.
-xlibmil inlines a function regardless of any specification of the function as part of the -xinline flag.
However, these substitutions can cause the setting of errno to become unreliable. If your program depends on the value of errno, avoid this option. See also Preserving the Value of errno.
Enables the compiler to use a library of optimized math routines. You must use default rounding mode by specifying -fround=nearest when you use this option.
The math routine library is optimized for performance and usually generates faster code. The results may be slightly different from those produced by the normal math library. If so, they usually differ in the last bit.
Note that these substitutions can cause the setting of errno to become unreliable. If your program depends on the value of errno, avoid this option. For more information, see Preserving the Value of errno.
The order on the command line for this library option is not significant.
This option is set by the -fast option.
See also -fast and -xnolibmopt.
(Obsolete) Use -library=sunperf to link with the Sun Performance Library.
This option is silently ignored by the compiler.
Instructs the compiler to perform link-time optimizations on relocatable object files. These optimizations are performed at link time by analyzing the object binary code. The object files are not rewritten but the resulting executable code might differ from the original object codes.
You must use -xlinkopt on at least some of the compilation commands for -xlinkopt to be useful at link time. The optimizer can still perform some limited optimizations on object binaries that are not compiled with -xlinkopt.
-xlinkopt optimizes code coming from static libraries that appear on the compiler command line, but does not optimize code coming from shared (dynamic) libraries that appear on the command line. You can also use -xlinkopt when you build shared libraries (compiling with -G ).
level sets the level of optimizations performed, and must be 0, 1, or 2. The optimization levels are listed in the following table:
|
If you compile in separate steps, -xlinkopt must appear on both compile and link steps.
example% cc -c -xlinkopt a.c b.c example% cc -o myprog -xlinkopt=2 a.o
For a complete list of all compiler options that must be specified at both compile time and at link time, see Table A–2.
Note that the level parameter is only used when the compiler is linking. In the example, the post- optimization level used is 2 even though the object binaries were compiled with an implied level of 1.
Specifying -xlinkopt without a level parameter implies -xlinkopt=1.
The -xlinkopt option requires profile feedback (-xprofile) in order to optimize the program. Profiling reveals the most- and least-used parts of the code, which enables the optimizer to focus its effort accordingly. Link-time optimization is particularly important with large applications where optimal placement of code can substantially reduce instruction cache misses. Additionally, -xlinkopt is most effective when used to compile the whole program. Use this option as follows:
example% cc -o progt -xO5 -xprofile=collect:prog file.c example% progt example% cc -o prog -xO5 -xprofile=use:prog -xlinkopt file.c
For details about using profile feedback, see –xprofile=p.
Do not use the -zcombreloc linker option when you compile with -xlinkopt.
Note that compiling with this option increases link time slightly. Object file sizes also increase, but the size of the executable remains the same. Compiling with -xlinkopt and -g increases the size of the executable by including debugging information.
Shows which loops are parallelized. Provides a brief reason for not parallelizing a loop. The -xloopinfo option is valid only if -xautopar is specified; otherwise, the compiler issues a warning.
To achieve faster execution, this option requires a multiprocessor system. On a single-processor system, the generated code usually runs slower.
Runs only the C preprocessor on the named C programs, requesting that the preprocessor generate makefile dependencies and send the result to the standard output. See the make(1) man page for details about make files and dependencies.
For example:
#include <unistd.h> void main(void) {}
generates this output:
e.o: e.c e.o: /usr/include/unistd.h e.o: /usr/include/sys/types.h e.o: /usr/include/sys/machtypes.h e.o: /usr/include/sys/select.h e.o: /usr/include/sys/time.h e.o: /usr/include/sys/types.h e.o: /usr/include/sys/time.h e.o: /usr/include/sys/unistd.h
If you specify -xM and -xMF, the compiler appends all makefile dependency information to the file specified with -xMF.
Generates makefile dependencies like -xM, but excludes /usr/include files. For example:
more hello.c #include<stdio.h> main() { (void)printf(“hello\n”); } cc– xM hello.c hello.o: hello.c hello.o: /usr/include/stdio.h
Compiling with -xM1 does not report header file dependencies:
cc– xM1 hello.c hello.o: hello.c
-xM1 is not available under -Xs mode.
If you specify -xM1 and -xMF, the compiler appends all makefile dependency information to the file specified with -xMF.
Generates makefile dependencies like -xM but compilation continues. -xMD generates an output file for the makefile-dependency information derived from the -o output filename, if specified, or the input source filename, replacing (or adding) the filename suffix with .d. If you specify -xMD and -xMF, the preprocessor writes all makefile dependency information to the file specified with -xMF. Compiling with -xMD -xMF or -xMD -o filename with more than one source file is not allowed and generates an error. The dependency file is overwritten if it already exists.
Use this option to specify a file for the makefile-dependency output. You cannot specify individual filenames for multiple input files with -xMF on one command line. Compiling with -xMD -xMF or -xMMD -xMF with more than one source file is not allowed and generates an error. The dependency file is overwritten if it already exists.
This option cannot be used with -xM or -xM1.
Use this option to generate makefile dependencies excluding system header files. This option provides the same functionality as -xM1, but compilation continues. -xMMD generates an output file for the makefile-dependency information derived from the -o output filename, if specified, or the input source filename, replacing (or adding) the filename suffix with .d . If you specify -xMF, the compiler uses the filename you provide instead. Compiling with -xMMD -xMF or -xMMD -o filename with more than one source file is not allowed and generates an error. The dependency file is overwritten if it already exists.
Merges data segments into text segments. Data initialized in the object file produced by this compilation is read-only and (unless linked with ld -N) is shared between processes.
The three options -xMerge -ztext -xprofile=collect should not be used together. While -xMerge forces statically initialized data into read-only storage, -ztext prohibits position-dependent symbol relocations in read-only storage, and -xprofile=collect generates statically initialized, position-dependent symbol relocations in writable storage.
This option limits the level of pragma opt to the level specified. v is one of off, 1, 2, 3, 4, 5. The default value is -xmaxopt=off which causes pragma opt to be ignored. Specifying -xmaxopt without supplying an argument is the equivalent of specifying -xmaxopt=5.
If you specify both -xO and -xmaxopt, the optimization level set with -xO must not exceed the -xmaxopt value.
(SPARC) Use the -xmemalign option to control the assumptions that the compiler makes about the alignment of data. By controlling the code generated for potentially misaligned memory accesses and by controlling program behavior in the event of a misaligned access, you can more easily port your code to the SPARC platform.
Specify the maximum assumed memory alignment and behavior of misaligned data accesses. You must provide a value for both a (alignment) and b (behavior). a specifies the maximum assumed memory alignment and b specifies the behavior for misaligned memory accesses. The following table lists the alignment and behavior values for -xmemalign.
|
You must specify -xmemalign whenever you want to link to an object file that was compiled with the value of b set to either i or f. For a complete list of all compiler options that must be specified at both compile time and at link time, see Table A–2.
For memory accesses where the alignment is determinable at compile time, the compiler generates the appropriate load/store instruction sequence for that alignment of data.
For memory accesses where the alignment cannot be determined at compile time, the compiler must assume an alignment to generate the needed load/store sequence. The -xmemalign option enables you to specify the maximum memory alignment of data to be assumed by the compiler in these situations. It also specifies the error behavior to be followed at run time when a misaligned memory access does take place.
If actual data alignment at runtime is less than the specified alignment, the misaligned access attempt (a memory read or write) generates a trap. The two possible responses to the trap are
The OS converts the trap to a SIGBUS signal. If the program does not catch the signal, the program stops. Even if the program catches the signal, the misaligned access attempt will not have succeeded.
The OS handles the trap by interpreting the misaligned access and returning control to the program as if the access had succeeded normally.
The following default values apply only when no -xmemalign option is present:
-xmemalgin=8i for all 32–bit platforms (-m32).
-xmemalign=8s for all 64–bit platforms (-m64).
The default when -xmemalign option is present but no value is given is -xmemalign=1i for all platforms.
The following table describes how you can use -xmemalign to handle different alignment situations.
|
(x86) The -xmodel option enables the compiler to modify the form of 64-bit objects for Oracle Solaris x86 platforms and should only be specified for the compilation of such objects.
This option is valid only when –m64 is also specified on 64–bit enabled x64 processors.
The following table lists the values for a.
|
This option is not cumulative so the compiler sets the model value according to the rightmost instance of -xmodel on the command line.
If you do not specify -xmodel, the compiler assumes -xmodel=small. Specifying -xmodel without an argument is an error.
You do not have to compile all translation units with this option. You can compile select files as long as you ensure the object you are accessing is within reach.
Be aware that not all Linux systems support the medium model.
Does not link any libraries by default; that is, no -l options are passed to ld(1). Normally, the cc driver passes -lc to ld.
When you use -xnolib, you have to pass all the -l options yourself.
Does not inline math library routines. Use this option after the –fast option for example:
% cc– fast– xnolibmil....
Prevents the use of an optimized math library by the compiler by disabling any previously specified -xlibmopt option. For example, use this option after -fast, which enables -xlibmopt.
% cc -fast -xnolibmopt ...
Do not build a runtime search path for shared libraries into the executable.
This option is recommended for building executables that will be shipped to customers who might have a different path for the shared libraries that are used by the program.
Sets the compiler optimization level. Note the uppercase letter O followed by the digit 1, 2, 3, 4, or 5. Generally, the higher the level of optimization, the better the runtime performance. However, higher optimization levels can result in longer compilation time and larger executable files.
In a few cases, -xO2 might perform better than the others, and -xO3 might outperform -xO4.
If the optimizer runs out of memory, it tries to recover by retrying the current procedure at a lower level of optimization and resumes subsequent procedures at the original level specified in the command-line option.
The default is no optimization, which is only possible if you do not specify an optimization level. If you specify an optimization level, you cannot disable optimization.
If you are trying to avoid setting an optimization level, be sure not to specify any option that implies an optimization level. For example, -fast is a macro option that sets optimization at -xO5. All other options that imply an optimization level issue a warning message that optimization has been set. The only way to compile without any optimization is to delete all options from the command line or makefile that specify an optimization level.
If you use -g 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 and the optimization level is -xO4 or higher, the compiler provides best-effort symbolic information with full optimization.
Debugging with -g does not suppress -xOn, but -xOn limits -g in certain ways. For example, the optimization 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 Optimized Code” in Chapter 1 of Debugging a Program With dbx.
If you specify both -xO and -xmaxopt, the optimization level set with -xO must not exceed the -xmaxopt value.
If you optimize at -xO3 or -xO4 with very large procedures (thousands of lines of code in the same procedure), the optimizer may require a large amount of virtual memory. In such cases, machine performance might degrade.
The following table lists the optimization levels on SPARC platforms.
|
The following table lists the optimization levels on x86 platforms.
|
For more information about debugging, see the Oracle Solaris Studio: Debugging a Program With dbx manual. For more information on optimization, see the Oracle Solaris Studio Performance Analyzer manual.
See also -xldscope and -xmaxopt.
Enable explicit parallelization with OpenMP directives.
The following table details the -xopenmp values:
|
If you specify -xopenmp but do not specify a value, the compiler assumes -xopenmp=parallel. If you do not specify -xopenmp at all, the compiler assumes -xopenmp=none.
If you are debugging an OpenMP program with dbx, compile with -g -xopenmp=noopt so you can breakpoint within parallel regions and display the contents of variables.
The default for -xopenmp might change in a future release. You can avoid warning messages by explicitly specifying an appropriate optimization level.
Use the OMP_NUM_THREADS environment variable to specify the number of threads to use when running an OpenMP program. If OMP_NUM_THREADS is not set, the default number of threads used to execute a parallel region is the number of cores available on the machine, capped at 32. You can specify a different number of threads by setting the OMP_NUM_THREADS environment variable, or by calling the omp_set_num_threads() OpenMP runtime routine, or by using the num_threads clause on the parallel region directive. For best performance, the number of threads used to execute a parallel region should not exceed the number of hardware threads (or virtual processors) available on the machine. On Oracle Solaris systems, this number can be determined by using the psrinfo(1M) command. On Linux systems, this number can be determined by inspecting the file /proc/cpuinfo. See the OpenMP API User's Guide for more information.
Nested parallelism is disabled by default. To enable nested parallelism, you must set the OMP_NESTED environment variable to TRUE. See the OpenMP API User's Guide for details.
If you compile and link in separate steps, specify -xopenmp in both the compilation step and the link step. When used with the link step, the -xopenmp option will link with the OpenMP runtime support library, libmtsk.so.
For up-to-date functionality and performance, make sure that the latest patch of the OpenMP runtime library, libmtsk.so, is installed on the system.
For more information about the OpenMP Fortran 95, C, and C++ application program interface (API) for building multithreaded applications, see the Oracle Solaris Studio OpenMP API User's Guide.
The compiler performs only syntax and semantic checking on the source file in order to print prototypes for all K&R C functions. This option does not produce any object or executable code. For example, specifying -xP with the following source file,
f() { } main(argc,argv) int argc; char *argv[]; { }
produces this output:
int f(void); int main(int, char **);
Sets the preferred page size for the stack and the heap.
SPARC: The following values are valid: 4k, 8K, 64K, 512K, 2M, 4M, 32M, 256M, 2G, 16G, or default.
x86: The following values are valid: 4K, 2M. 4M, 1G, or default.
If you do not specify a valid page size, the request is silently ignored at runtime. You must specify a valid page size for the target platform.
Use the pagesize(1) Oracle Solaris command to determine the number of bytes in a page. The operating system offers no guarantee that the page size request will be honored. However, appropriate segment alignment can be used to increase the likelihood of obtaining the requested page size. See the -xsegment_align option on how to set the segment alignment. You can use pmap(2) or meminfo(2) to determine page size of the target platform.
The -xpagesize option has no effect unless you use it at compile time and at link time. For a complete list of all compiler options that must be specified at both compile time and at link time, see Table A–2.
If you specify -xpagesize=default, the Oracle Solaris operating system sets the page size.
Compiling with this option has the same effect as setting the LD_PRELOAD environment variable to mpss.so.1 with the equivalent options, or running the Oracle Solaris command ppgsz(1) with the equivalent options before running the program. See the related Oracle Solaris man pages for details.
This option is a macro for -xpagesize_heap and -xpagesize_stack. These two options accept the same arguments as -xpagesize. You can set both options with the same value by specifying -xpagesize or you can specify them individually with different values.
Set the page size in memory for the heap.
This option accepts the same values as —xpagesize. If you do not specify a valid page size, the request is silently ignored at run-time.
Use the getpagesize(3C) command on the Oracle Solaris operating system to determine the number of bytes in a page. The Oracle Solaris operating system offers no guarantee that the page size request will be honored. You can use pmap(1) or meminfo(2) to determine page size of the target platform.
If you specify -xpagesize_heap=default, the Oracle Solaris operating system sets the page size.
Compiling with this option has the same effect as setting the LD_PRELOAD environment variable to mpss.so.1 with the equivalent options, or running the Oracle Solaris command ppgsz(1) with the equivalent options before running the program. See the related Oracle Solaris man pages for details.
The -xpagesize_heap option has no effect unless you use it at compile time and at link time. For a complete list of all compiler options that must be specified at both compile time and at link time, see Table A–2.
Set the page size in memory for the stack.
This option accepts the same values as —xpagesize. If you do not specify a valid page size, the request is silently ignored at run-time.
Use the getpagesize(3C) command on the Oracle Solaris operating system to determine the number of bytes in a page. The Oracle Solaris operating system offers no guarantee that the page size request will be honored. You can use pmap(1) or meminfo(2) to determine page size of the target platform.
If you specify -xpagesize_stack=default, the Oracle Solaris operating system sets the page size.
Compiling with this option has the same effect as setting the LD_PRELOAD environment variable to mpss.so.1 with the equivalent options, or running the Oracle Solaris command ppgsz(1) with the equivalent options before running the program. See the related Oracle Solaris man pages for details.
The -xpagesize_stack option has no effect unless you use it at compile time and at link time. For a complete list of all compiler options that must be specified at both compile time and at link time, see Table A–2.
Reserve an area of memory before the start of each function. If fix is specified, the compiler will reserve the amount of space required by fix and continue. This is the first default. If either patch or no value is specified, the compiler will reserve a platform-specific default value. A value of -xpatchpadding=0 will reserve 0 bytes of space. The maximum value for size on x86 is 127 bytes and on SPARC is 2048 bytes.
This compiler option activates the precompiled-header feature. v can be auto, autofirst, collect:pch_filename, or use:pch_filename. You can take advantage of this feature through the -xpch and -xpchstop options in combination with the #pragma hdrstop directive.
Use the -xpch option to create a precompiled-header file and improve your compilation time. The precompiled-header file reduces compile time for applications whose source files share a common set of include files containing a large amount of source code. A precompiled header works by collecting information about a sequence of header files from one source file, and then using that information when recompiling that source file, and when compiling other source files that have the same sequence of headers. The information that the compiler collects is stored in a precompiled-header file.
For more information, see:
The compiler can generate the precompiled- header file for you automatically in one of two ways. One way is for the compiler to create the precompiled-header file from the first include file it finds in the source file. The other way is for the compiler to select from the set of include files found in the source file starting with the first include file and extending through a well-defined point that determines which include file is the last one. Use one of the flags described in the following table to determine which method the compiler uses to automatically generate a precompiled header.
|
To create your precompiled-header file manually, start by first using -xpch, and specifying the collect mode. The compilation command that specifies -xpch=collect must only specify one source file. In the following example, the -xpch option creates a precompiled-header file called myheader.cpch based on the source file a.c.
cc -xpch=collect:myheader a.c
A valid precompiled-header file name always has the suffix .cpch. When you specify pch_filename, you can add the suffix or have the compiler add it for you. For example, if you specify cc -xpch=collect:foo a.c, the precompiled-header file is called foo.cpch.
If the compiler cannot use the precompiled-header file with -xpch=auto and -xpch=autofirst, it generates a new precompiled-header file. If the compiler cannot use the precompiled-header file with -xpch=use, a warning is issued and the compilation is done using the real headers.
You can also direct the compiler to use a specific precompiled header by specifying -xpch=use:pch_filename. You can specify any number of source files with the same sequence of include files as the source file that was used to create the precompiled-header file. For example, your command in use mode might be: cc -xpch=use:foo.cpch foo.c bar.c foobar.c.
You should only use an existing precompiled-header file if the following items are true. If any of the following is not true, you should re-create the precompiled-header file:
The compiler that you are using to access the precompiled-header file is the same as the compiler that created the precompiled-header file. A precompiled-header file created by one version of the compiler might not be usable by another version of the compiler.
Except for the -xpch option, the compiler options you specify with -xpch=use must match the options that were specified when the precompiled-header file was created.
The set of included headers you specify with -xpch=use is identical to the set of headers that were specified when the precompile header was created.
The contents of the included headers that you specify with -xpch=use is identical to the contents of the included headers that were specified when the precompiled header was created.
The current directory (that is, the directory in which the compilation is occurring and attempting to use a given precompiled-header file) is the same as the directory in which the precompiled-header file was created.
The initial sequence of preprocessing directives, including #include directives, in the file you specified with -xpch=collect are the same as the sequence of preprocessing directives in the files you specify with -xpch=use.
In order to share a precompiled-header file across multiple source files, those source files must share a common set of include files as their initial sequence of tokens. A token is a keyword, name or punctuation mark. Comments and code that is excluded by #if directives are not recognized by the compiler as tokens. This initial sequence of tokens is known as the viable prefix. In other words, the viable prefix is the top portion of the source file that is common to all source files. The compiler uses this viable prefix as the basis for creating a precompiled-header file and thereby determining which header files from the source are precompiled.
The viable prefix that the compiler finds during the current compilation must match the viable prefix that it used to create the precompiled-header file. In other words, a viable prefix must be interpreted consistently across all the source files that use the same precompiled-header file.
The viable prefix of a source file can only consist of comments and any of the following preprocessor directives:
#include #if/ifdef/ifndef/else/elif/endif #define/undef #ident (if identical, passed through as is) #pragma (if identical)
Any of these directives may reference macros. The #else, #elif, and #endif directives must match within the viable prefix. Comments are ignored.
The compiler determines the end point of the viable prefix automatically when you specify -xpch=auto or -xpch=autofirst. It is defined as follows.
The first declaration/definition
The first #line directive
A #pragma hdrstop directive
After the named include file if you specify –xpch=auto and –xpchstop
The first include file if you specify –xpch=autofirst
For -xpch=collect or -xpch=use, the viable prefix ends with a #pragma hdrstop.
Within the viable prefix of each file that shares a precompiled-header file, each corresponding #define and #undef directive must reference the same symbol. In the case of #define, each one must reference the same value. Their order of appearance within each viable prefix must be the same as well. Each corresponding pragma must also be the same and appear in the same order across all the files sharing a precompiled header.
A header file is precompilable when it is interpreted consistently across different source files; specifically, when it contains only complete declarations. That is, a declaration in any one file must stand alone as a valid declaration. Incomplete type declarations, such as struct S;, are valid declarations. The complete type declaration can appear in some other file. Consider these example header files:
file a.h struct S { #include "x.h" /* not allowed */ }; file b.h struct T; // ok, complete declaration struct S { int i; [end of file, continued in another file] /* not allowed*/
A header file that is incorporated into a precompiled-header file must not violate the following constraints. The results of compiling a program that violates any of these constraints is undefined.
The header file must not use __DATE__ and __TIME__.
The header file must not contain #pragma hdrstop.
A header is also precompilable if it contains variable and function definitions. as well.
When the compiler creates a precompiled-header file automatically, the compiler writes it to the SunWS_cache directory. This directory always resides in the location where the object file is created. Updates to the file are performed under a lock so that it works properly under dmake.
If you need to force the compiler to rebuild automatically generated precompiled-header files, you can clear the precompiled-header file cache-directory with the CCadmin tool. See the CCadmin(1) man page for more information.
Do not specify conflicting -xpch flags on the command line. For example, specifying both -xpch=collect and -xpch=auto, or specifying both -xpch=autofirst with -xpchstop=<include> generates an error.
If you specify -xpch=autofirst or you specify -xpch=auto without -xpchstop, any declaration, definition, or #line directive that appears prior to the first include file, or appears prior to the include file that is specified with -xpchstop for -xpch=auto, generates a warning and disables the automatic generation of the precompiled-header file.
A #pragma hdrstop before the first include file under -xpch=autofirst or -xpch=auto disables the automatic generation of the precompiled-header file.
The compiler generates dependency information for precompiled-header files when you specify -xpch=collect. You need to create the appropriate rules in your make files to take advantage of these dependencies. Consider this sample make file:
%.o : %.c shared.cpch $(CC) -xpch=use:shared -xpchstop=foo.h -c $< default : a.out foo.o + shared.cpch : foo.c $(CC) -xpch=collect:shared -xpchstop=foo.h foo.c -c a.out : foo.o bar.o foobar.o $(CC) foo.o bar.o foobar.o clean : rm -f *.o shared.cpch .make.state a.out
These make rules, along with the dependencies generated by the compiler, force a manually created precompiled- header file to be re-created if any source file you used with -xpch=collect, or any of the headers that are part of the precompiled-header file, have changed. This constraint prevents the use of an out-of-date precompiled-header file.
You do not have to create any additional make rules in your makefiles for -xpch=auto or -xpch=autofirst.
Use the -xpchstop=file option to specify the last include file of the viable prefix for the precompiled-header file. Using -xpchstop on the command line is equivalent to placing a hdrstop pragma after the first include-directive that references file in each of the source files that you specify with the cc command.
Use -xpchstop=<include> with -xpch-auto to create a precompiled-header file that is based on header files up through and including <include>. This flag overrides the default -xpch=auto behavior of using all header files that are contained in the entire viable prefix.
In the following example, the -xpchstop option specifies that the viable prefix for the precompiled-header file ends with the include of projectheader.h. Therefore, privateheader.h is not a part of the viable prefix.
example% cat a.c #include <stdio.h> #include <strings.h> #include "projectheader.h" #include "privateheader.h" . . . example% cc -xpch=collect:foo.cpch a.c -xpchstop=projectheader.h -c
See also -xpch.
(Solaris only) Generates a Portable Executable Code (PEC) binary. This option puts the program intermediate representations in the object file and the binary. This binary may be used later for tuning and troubleshooting.
A binary that is built with –xpec is usually five to ten times larger than if it is built without –xpec.
If you do not specify –xpec, the compiler assumes –xpec=no. If you specify –xpec, but do not supply a flag, the compiler assumes –xpec=yes.
(x86) Generates code for the Pentium processor.
Prepares the object code to collect data for profiling with gprof(1). It invokes a runtime recording mechanism that produces a gmon.out file at normal termination.
Profiles are generated by using prof(1) or gprof(1) on 64–bit Oracle Solaris platforms or just gprof on 32–bit Oracle Solaris platforms and include approximate user CPU times derived from PC sample data (see pcsample(2)) for routines in the main executable and routines in shared libraries specified as linker arguments when the executable is linked. Other shared libraries (libraries opened after process startup using dlopen(3DL)) are not profiled.
On 32–bit Oracle Solaris systems, profiles generated using prof(1) are limited to routines in the executable. 32–bit shared libraries can be profiled by linking the executable with -xpg and using gprof(1).
On x86 systems, -xpg is incompatible with -xregs=frameptr. These two options should not be used together. Note also that -xregs=frameptr is included in -fast. Compile with -fast -xregs=no%frameptr -xpg when using -fast with -xpg.
Current Oracle Solaris releases do not include system libraries compiled with -p. As a result, profiles collected current Solaris platforms do not include call counts for system library routines.
If you specify -xpg at compile time, you must also specify it at link time. See Compile-Time and Link-Time Options for a complete list of options that must be specified at both compile time and link time.
Enables prefetch instructions on those architectures that support prefetch.
Explicit prefetching should be used only under special circumstances that are supported by measurements.
The following table lists the values of val.
|
The default is -xprefetch=auto,explicit. This default adversely affects applications that have essentially non-linear memory access patterns. Specify -xprefetch=no%auto,no%explicit to override the default.
The sun_prefetch.h header file provides the macros that you can use to specify explicit prefetch instructions. The prefetches are approximately at the place in the executable that corresponds to where the macros appear.
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 factor must be a positive number of the form n.n.
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. The assumed latency between a prefetch and a load might 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 might 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 data sets that reside entirely within the external cache, you might be able to obtain better performance by decreasing the prefetch latency values. To decrease the values, use a factor that is less than one.
To use the latx:factor suboption, start with a factor value near 1.0 and run performance tests against the application. 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 performance will level off again.
The value for a is [no%]indirect_array_access.
Use -xprefetch_auto_type=indirect_array_access to enable the compiler to generate indirect prefetches for the loops indicated by the option -xprefetch_level in the same fashion the prefetches for direct memory accesses are generated.
If you do not specify a setting for -xprefetch_auto_type, the compiler sets it to -xprefetch_auto_type=no%indirect_array_access.
Options such as -xalias_level can affect the aggressiveness of computing the indirect prefetch candidates and therefore the aggressiveness of the automatic indirect prefetch insertion due to better memory alias disambiguation information.
Use the -xprefetch_level option to control the aggressiveness of automatic insertion of prefetch instructions as determined with -xprefetch=auto. l must be 1, 2, or 3. The compiler becomes more aggressive, or in other words, introduces more prefetches with each higher level of -xprefetch_level.
The appropriate value for the -xprefetch_level depends on the number of cache misses the application has. Higher -xprefetch_level values have the potential to improve the performance of applications.
This option is effective only when it is compiled with -xprefetch=auto with optimization level 3 or greater, and generate codes for a platform that supports prefetch (v8plus, v8plusa, v9, v9a, v9b, sse2, sse2a, sse3, amdsse4a, sse4_1, sse4_2, aes, avx, avx_i, avx2, generic64, and native64).
-xprefetch_level=1 enables automatic generation of prefetch instructions. -xprefetch_level=2 enables additional generation beyond level 1. -xprefetch_level=3 enables additional generation beyond level 2.
The default is -xprefetch_level=1 when you specify -xprefetch=auto.
Compile with this option to produce a static analysis of the source code that can be viewed using the Code Analyzer.
When compiling with -xprevise=yes and linking in a separate step, include -xprevise=yes also on the link step.
The default is -xprevise=no.
On Linux, -xprevise=yes needs to be specified along with -xannotate.
See the Oracle Solaris Studio Code Analyzer documentation for further information.
Collects data for a profile or uses a profile to optimize.
p must be collect[:profdir], use[:profdir], or tcov[:profdir].
This option causes execution frequency data to be collected and saved during execution. The data can be used in subsequent runs to improve performance. Profile collection is safe for multithreaded applications. That is, profiling a program that does its own multitasking ( -mt ) produces accurate results. This option is valid only when you specify -xO2 or greater level of optimization. If compilation and linking are performed in separate steps, the same -xprofile option must appear on the link step as well as the compile step.
Collects and saves execution frequency for later use by the optimizer with -xprofile=use. The compiler generates code to measure statement execution-frequency.
-xMerge, -ztext, and -xprofile=collect should not be used together. While -xMerge forces statically initialized data into read-only storage, -ztext prohibits position-dependent symbol relocations in read-only storage, and -xprofile=collect generates statically initialized, position-dependent symbol relocations in writable storage.
The profile directory name profdir, if specified, is the pathname of the directory where profile data are to be stored when a program or shared library containing the profiled object code is executed. If the profdir pathname is not absolute, it is interpreted relative to the current working directory when the program is compiled with the option -xprofile=use:profdir.
If no profile directory name is specified with —xprofile=collect:prof_dir or —xprofile=tcov:prof_dir, profile data are stored at run time in a directory named program.profile where program is the basename of the profiled process's main program. In this case, the environment variables SUN_PROFDATA and SUN_PROFDATA_DIR can be used to control where the profile data are stored at run time. If set, the profile data are written to the directory given by $SUN_PROFDATA_DIR/$SUN_PROFDATA. If a profile directory name is specified at compilation time, SUN_PROFDATA_DIR and SUN_PROFDATA have no effect at run time. These environment variables similarly control the path and names of the profile data files written by tcov, as described in the tcov(1) man page.
If these environment variables are not set, the profile data is written to the directory profdir.profile in the current directory, where profdir is the name of the executable or the name specified in the -xprofile=collect:profdir flag. -xprofile does not append .profile to profdir if profdir already ends in .profile. If you run the program several times, the execution frequency data accumulates in the profdir.profile directory; that is output from prior executions is not lost.
If you are compiling and linking in separate steps, make sure that any object files compiled with -xprofile=collect are also linked with -xprofile=collect.
The following example collects and uses profile data in the directory myprof.profile located in the same directory where the program is built:
demo: cc -xprofile=collect:myprof.profile -xO5 prog.c -o prog demo: ./prog demo: cc -xprofile=use:myprof.profile -xO5 prog.c -o prog
The following example collects profile data in the directory /bench/myprof.profile and later uses the collected profile data in a feedback compilation at optimization level -xO5:
demo: cc -xprofile=collect:/bench/myprof.profile \ -xO5 prog.c -o prog ...run prog from multiple locations.. demo: cc -xprofile=use:/bench/myprof.profile \ -xO5 prog.c -o prog
Uses execution frequency data collected from code compiled with —xprofile=collect[:profdir] or —xprofile=tcov[:profdir] to optimize for the work performed when the profiled code was executed. profdir is the pathname of a directory containing profile data collected by running a program that was compiled with —xprofile=collect[:profdir] or —xprofile=tcov[:profdir].
To generate data that can be used by both tcov and —xprofile=use[:profdir], a profile directory must be specified at compilation time, using the option —xprofile=tcov[:profdir]. The same profile directory must be specified in both —xprofile=tcov:profdir and —xprofile=use:profdir. To minimize confusion, specify profdir as an absolute pathname.
The profdir path name is optional. If profdir is not specified, the name of the executable binary is used. a.out is used if -o is not specified. The compiler looks for profdir.profile/feedback, or a.out.profile/feedback when profdir is not specified. For example:
demo: cc -xprofile=collect -o myexe prog.c demo: cc -xprofile=use:myexe -xO5 -o myexe prog.c
The program is optimized by using the execution frequency data previously generated and saved in the feedback files written by a previous execution of the program compiled with -xprofile=collect.
Except for the -xprofile option, the source files and other compiler options must be exactly the same as those used for the compilation that created the compiled program that generated the feedback file. The same version of the compiler must be used for both the collect build and the use build as well.
If compiled with -xprofile=collect:profdir, the same profile directory name profdir must be used in the optimizing compilation: -xprofile=use:profdir.
See also -xprofile_ircache for speeding up compilation between collect and use phases.
Instrument object files for basic block coverage analysis using tcov(1).
If the optional profdir argument is specified, the compiler will create a profile directory at the specified location. The data stored in the profile directory can be used either by tcov(1) or by the compiler with -xprofile=use:profdir. If the optional profdir path name is omitted, a profile directory will be created when the profiled program is executed. The data stored in the profile directory can be used only by tcov(1). The location of the profile directory can be controlled using environment variables SUN_PROFDATA and SUN_PROFDATA_DIR.
If the location specified by profdir is not an absolute path name, it is interpreted at compilation time relative to the current working directory.
The directory whose location is specified by profdir must be accessible from all machines where the profiled program is to be executed. The profile directory should not be deleted until its contents are no longer needed, because data stored there by the compiler cannot be restored except by recompilation.
Example 1: If object files for one or more programs are compiled with -xprofile=tcov:/test/profdata, a directory named /test/profdata.profile will be created by the compiler and used to store data describing the profiled object files. The same directory will also be used at execution time to store execution data associated with the profiled object files.
Example 2: If a program named myprog is compiled with -xprofile=tcov and executed in the directory /home/joe, the directory /home/joe/myprog.profile will be created at runtime and used to store runtime profile data.
(SPARC) Use -xprofile_ircache[=path] with -xprofile=collect|use to improve compilation time during the use phase by reusing compilation data saved from the collect phase.
With large programs, compilation time in the use phase can improve significantly because the intermediate data is saved. Note that the saved data could increase disk space requirements considerably.
When you use -xprofile_ircache[=path], path overrides the location where the cached files are saved. By default, these files are saved in the same directory as the object file. Specifying a path is useful when the collect and use phases happen in two different directories. The following example shows a typical sequence of commands:
example% cc -xO5 -xprofile=collect -xprofile_ircache t1.c t2.c example% a.out // run collects feedback data example% cc -xO5 -xprofile=use -xprofile_ircache t1.c t2.c
(SPARC) Use the -xprofile_pathmap=collect_prefix:use_prefix option when you are also specifying the -xprofile=use command. Use -xprofile_pathmap when both of the following are true and the compiler is unable to find profile data for an object file that is compiled with -xprofile=use.
You are compiling the object file with -xprofile=use in a directory that is different from the directory in which the object file was previously compiled with -xprofile=collect.
Your object files share a common base name in the profile but are distinguished from each other by their location in different directories.
The collect-prefix is the prefix of the UNIX path name of a directory tree in which object files were compiled using -xprofile=collect.
The use-prefix is the prefix of the UNIX pathname of a directory tree in which object files are to be compiled using -xprofile=use.
If you specify multiple instances of -xprofile_pathmap, the compiler processes them in the order of their occurrence. Each use-prefix specified by an instance of -xprofile_pathmap is compared with the object file pathname until either a matching use-prefix is identified or the last specified use-prefix is found not to match the object file path name.
Analyzes loops for reduction in automatic parallelization. This option is valid only if -xautopar is also specified. Otherwise the compiler issues a warning.
When a reduction recognition is enabled, the compiler parallelizes reductions such as dot products and maximum and minimum finding. These reductions yield roundoffs different from those obtained by unparallelized code.
See also the Oracle Solaris Studio OpenMP API User's Guide.
Specifies the usage of registers for the generated code.
r is a comma-separated list that consists of one or more of the following suboptions: appl, float,frameptr.
Prefixing a suboption with no% disables that suboption.
Note that —xregs suboptions are restricted to specific hardware platforms.
Example: -xregs=appl,no%float
|
The SPARC default is -xregs=appl,float.
The x86 default is -xregs=no%frameptr,float.
On x86 systems, -xpg is incompatible with -xregs=frameptr. These two options should not be used together. Note also that -xregs=frameptr is included in -fast.
You should compile code intended for shared libraries that will link with applications with -xregs=no%appl,float. At the very least, the shared library should explicitly document how it uses the application registers so that applications linking with those libraries are aware of these register assignments.
For example, an application using the registers in some global sense (such as using a register to point to some critical data structure) would need to be aware of how a library with code compiled without -xregs=no%appl is using the application registers in order to safely link with that library.
Treats pointer-valued function parameters as restricted pointers. f is %all, %none, or a comma-separated list of one or more function names: {%all|%none|fn[,fn...]}.
If a function list is specified with this option, pointer parameters in the specified functions are treated as restricted. If -xrestrict=%all is specified, all pointer parameters in the entire C file are treated as restricted. Refer to Restricted Pointers for more information.
This command-line option can be used on its own, but it is best used with optimization. For example, the command treats all pointer parameters in the file prog.c as restricted pointers:
%cc -xO3 -xrestrict=%all prog.c
The command treats all pointer parameters in the function agc in the file prog.c as restricted pointers:
%cc -xO3 -xrestrict=agc prog.c
The default is %none. Specifying -xrestrict is equivalent to specifying -xrestrict=%all.
(Oracle Solaris) Link debug information from object files into executable.
-xs is the same as -xs=yes.
The default for -xdebugformat=dwarf is the same as -xs=yes.
The default for -xdebugformat=stabs is the same as -xs=no.
This option controls the trade-off of executable size versus the need to retain object files in order to debug. For dwarf, use -xs=no to keep the executable small but depend on the object files. For stabs, use -xs or -xs=yes to avoid dependence on the object files at the cost of a larger executable. This option has almost no effect on dbx performance or the runtime per formance of the program.
When the compile command forces linking (that is, -c is not specified) there will be no object file(s) and the debug information must be placed in the executable. In this case, -xs=no (implicit or explicit) will be ignored.
The feature is implemented by having the compiler adjust the section flags and/or section names in the object file that it emits, which then tells the linker what to do for that object file's debug information. It is therefore a compiler option, not a linker option. It is possible to have an executable with some object files compiled -xs=yes and others compiled -xs=no.
Linux compilers accept but ignore -xs. Linux compilers do not accept -xs={yes|no}.
(SPARC) Allows the compiler to assume no memory protection violations occur.
This option grants permission to use non-faulting load instruction on the SPARC V9 architecture.
This option takes effect only when used with optimization level –xO5 and one of the following –xarch values: sparc, sparcvis, sparcvis2, or sparcvis3 for both –m32 and –m64.
(Oracle Solaris) This option causes the driver to include a special mapfile on the link line. The mapfile aligns the text, data, and bss segments to the value specified by n. When using very large pages, it is important that the heap and stack segments are aligned on an appropriate boundary. If these segments are not aligned, small pages will be used up to the next boundary, which could cause a performance degradation. The mapfile ensures that the segments are aligned on an appropriate boundary.
The n value must be one of the following:
SPARC: The following values are valid: 8K, 64K, 512K, 2M, 4M, 32M, 256M, 1G, and none.
x86: The following values are valid: 4K, 8K, 64K, 512K, 2M, 4M, 32M, 256M, 1G, and none.
The default for both SPARC and x86 is none.
Recommended usage is as follows:
SPARC 32-bit compilation: -xsegment_align=64K SPARC 64-bit compilation: -xsegment_align=4M x86 32-bit compilation: -xsegment_align=8K x86 64-bit compilation: -xsegment_align=4M
The driver will include the appropriate mapfile. For example, if the user specifies -xsegment_align=4M, the driver adds -M install-directory/lib/compilers/mapfiles/map.4M.align to the link line, where install-directory is the installation directory. The aforementioned segments will then be aligned on a 4M boundary.
Represents unsuffixed floating-point constants as single precision instead of the default mode of double precision. Not valid with -pedantic.
Does no optimizations or parallelization of loops that increase code size.
Example: The compiler will not unroll loops or parallelize loops if it increases code size.
This option is deprecated and might be removed in a future release. —xstrconst is an alias for —features=conststrings.
Specifies the target system for instruction set and optimization.
The value of t must be one of the following: native, generic, native64, generic64, or system-name.
Each specific value for -xtarget expands into a specific set of values for the -xarch, -xchip, and -xcache options. Use the -xdryrun option to determine the expansion of -xtarget=native on a running system.
For example, -xtarget=ultra4 is equivalent to -xchip=ultra4 -xcache=64/32/4:8192/128/2 -xarch=sparcvis2
|
The performance of some programs may 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, especially 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.
Compiling for 64-bit Oracle Solaris software on SPARC or UltraSPARC V9 is indicated by the –m64 option. If you specify –xtarget with a flag other than native64 or generic64, you must also specify the –m64 option as follows: –xtarget=ultra... –m64. Otherwise the compiler uses a 32-bit memory model.
|
Compiling for 64-bit Oracle Solaris software on 64-bit x86 platforms is indicated by the –m64 option. If you specify –xtarget with a flag other than native64 or generic64, you must also specify the –m64 option as follows:
–xtarget=opteron ... –m64
Otherwise the compiler uses a 32-bit memory model.
|
Specify -xthreadvar to control the implementation of thread local variables. Use this option in conjunction with the __thread declaration specifier to take advantage of the compiler’s thread-local storage facility. After you declare the thread variables with the __thread specifier, specify -xthreadvar to enable the use of thread-local storage with position dependent code (non-PIC code) in dynamic (shared) libraries. For more information about how to use __thread, see Thread Local Storage Specifier.
o must be dynamic or no%dynamic.
|
If you do not specify -xthreadvar, the default used by the compiler depends upon whether position-independent code is enabled. If position-independent code is enabled, the option is set to -xthreadvar=dynamic. If position-independent code is disabled, the option is set to -xthreadvar=no%dynamic.
If you specify -xthreadvar but do not specify any values, the option is set to -xthreadvar=dynamic.
If a dynamic library contains non-position-independent code, you must specify -xthreadvar.
The linker cannot support the thread-variable equivalent of non-PIC code in dynamic libraries. Non-PIC thread variables are significantly faster, and therefore should be the default for executables.
See also the descriptions of -xcode, -KPIC, and -Kpic
The -xthroughput option tells the compiler that the application will be run in situations where many processes are simultaneously running on the system
If -xthroughput=yes, the compiler will favor optimizations that slightly reduce performance for a single process while improving the amount of work achieved by all the processes on the system. As an example, the compiler might choose to be less aggressive in prefetching data. Such a choice would reduce the memory bandwidth consumed by the process, and as such the process may run slower, but it would also leave more memory bandwidth to be shared among other processes.
The default is -xthroughput=no.
Reports the time and resources used by each compilation component.
Issues warnings for the differences between K&R C and Solaris Studio ISO C.
The -xtransition option issues warnings in conjunction with the -Xa and -Xt options. You can eliminate all warning messages about differing behavior through appropriate coding. The following warnings no longer appear unless you issue the -xtransition option:
\a is ISO C “alert” character
\x is ISO C hex escape
bad octal digit
base type is really type tag: name
comment is replaced by “##”
comment does not concatenate tokens
declaration introduces new type in ISO C: type tag
macro replacement within a character constant
macro replacement within a string literal
no macro replacement within a character constant
no macro replacement within a string literal
operand treated as unsigned
trigraph sequence replaced
ISO C treats constant as unsigned: operator
semantics of operator change in ISO C; use explicit cast
The -xtrigraphs option determines whether the compiler recognizes trigraph sequences as defined by the ISO C standard.
By default, the compiler assumes -xtrigraphs=yes and recognizes all trigraph sequences throughout the compilation unit.
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 disable the recognition of trigraph sequences. The -xtrigraphs=no option disables recognition of all trigraphs throughout the entire compilation unit.
Consider the following example source file named trigraphs_demo.c.
#include <stdio.h> int main () { (void) printf("(\?\?) in a string appears as (??)\n"); return 0; }
The following examples shows the output if you compile this code with -xtrigraphs=yes.
example% cc -xtrigraphs=yes trigraphs_demo.c example% a.out (??) in a string appears as (]
The following example shows the output if you compile this code with -xtrigraphs=no.
example% cc -xtrigraphs=no trigraphs_demo.c example% a.out (??) in a string appears as (??)
Specify whether the program contains references to dynamically bound symbols.
-xunboundsym=yes means the program contains references dynamically bound symbols.
-xunboundsym=no means the program does not contain references to dynamically bound symbols.
The default is -xunboundsym=no.
Suggests to the optimizer to unroll loops n times. n is a positive integer. When n is 1, it requires the compiler not to unroll loops. When n is greater than 1, -xunroll=n suggests that the compiler unroll loops n times where appropriate.
Use this option if you need to support an internationalized application that uses ISO10646 UTF-16 string literals. In other words, use this option if your code contains a string literal that you want the compiler to convert to UTF-16 strings in the object file. Without this option, the compiler neither produces nor recognizes 16–bit character string literals. This option enables recognition of the U"ASCII_string" string literals as an array of type unsigned short int. Because such strings are not yet part of any standard, this option enables recognition of non-standard C.
You can turn off compiler recognition of U”ASCII_string” string literals by specifying -xustr=no. The right-most instance of this option on the command line overrides all previous instances.
The default is -xustr=no. If you specify -xustr without an argument, the compiler won’t accept it and instead issues a warning. The default can change if the C or C++ standards define a meaning for the syntax.
You can specify -xustr=ascii_utf16_ushort without also specifying a U"ASCII_string" string literals.
Specifying the flag -xustr=ascii_utf16_ushort results in an error if -std=c11 (including the default) is in effect. One of -Xc, -Xa, -Xt, -Xs, -xc99, -std=c99, -std=c89, or -ansi must also be specified when -xustr=ascii_utf16_ushort is specified.
Not all files have to be compiled with this option.
The following example shows a string literal in quotes that is prepended by U. It also shows a command line that specifies -xustr.
example% cat file.c const unsigned short *foo = U"foo"; const unsigned short bar[] = U"bar"; const unsigned short *fun() { return foo;} example% cc -xustr=ascii_utf16_ushort file.c -c
An 8-bit character literal can be prepended with U to form a 16-bit UTF-16 character of type unsigned short. Examples:
const unsigned short x = U'x'; const unsigned short y = U'\x79';
Enable automatic generation of calls to the vector library functions or the generation of the SIMD (Single Instruction Multiple Data) instructions on x86 processors that support SIMD. You must use default rounding mode by specifying -fround=nearest when you use this option.
The following table lists the values of a. The no% prefix disables the associated suboption.
|
The default is -xvector=simd on x86 and -xvector=%none on SPARC platforms. If you specify -xvector without a suboption, the compiler assumes -xvector=simd,lib on x86 Solaris, -xvector=lib on SPARC Solaris, and -xvector=simd on Linux platforms.
The -xvector option requires optimization level -xO3 or greater. Compilation will not proceed if the optimization level is unspecified or lower than -xO3, and a message is issued.
The compiler includes the libmvec libraries in the load step. If you compile and link in separate steps, use the same -xvector option on both commands.
(SPARC) Use the -xvis=[yes|no] command when you are using the vis.h header to generate VIS instructions, or when using assembler inline code (.il) that use VIS instructions. The default is -xvis=no. Specifying -xvis is equivalent to specifying -xvis=yes.
The VIS instruction set is an extension to the SPARC-V9 instruction set. Even though the UltraSPARC processors are 64-bit, there are many cases, especially in multimedia applications, when the data are limited to 8 or 16 bits in size. The VIS instructions can process four 16-bit data with one instruction so they greatly improve the performance of applications that handle new media such as imaging, linear algebra, signal processing, audio, video, and networking.
Issues warnings about potential parallel-programming related problems that might cause incorrect results when using OpenMP. Use with -xopenmp and OpenMP API directives.
The compiler issues warnings when it detects the following situations:
Loops are parallelized using MP directives with data dependencies between different loop iterations
OpenMP data-sharing attributes clauses are problematic. For example, declaring a variable "shared" whose accesses in an OpenMP parallel region might cause a data race, or declaring a variable "private" whose value in a parallel region is used after the parallel region.
No warnings appear if all parallelization directives are processed without problems.
Example:
cc -xopenmp -vpara any.c
Specifies a new directory dir for the location of component c. c can consist of any of the characters representing components that are listed under the -W option.
If the location of a component is specified, then the new path name for the tool is dir/tool. If more than one -Y option is applied to any one item, then the last occurrence holds.
Specifies a directory dir to search for all compiler components. If a component is not found in dir, the search reverts to the directory where the compiler is installed.
Changes the default directory that is searched for include files.
Changes the default directory for finding library files.
Changes the default directory for startup object files.
(SPARC) Creates the program database for lock_lint but does not generate executable code. Refer to the lock_lint(1) man page for more details.
cc recognizes -a, -e, -r, -t, -u, and -z and passes these options and their arguments to ld. cc passes any unrecognized options to ld with a warning. On Oracle Solaris platforms, the -i option and its arguments are also passed to the linker.
The default compiler options file enables the user to specify a set of default options that are applied to all compiles, unless otherwise overridden. For example, the file could specify that all compiles default at —xO2, or automatically include the file setup.il.
At startup, the compiler searches for a default options file listing default options it should include for all compiles. The environment variable SPRO_DEFAULTS_PATH specifies a colon separated list of directories to search for the defaults file.
If the environment variable is not set, a standard set of defaults is used. If the environment variable is set but is empty, no defaults are used.
The defaults file name must be of the form compiler.defaults, where compiler is one of the following: cc, c89, c99, CC, ftn, or lint. For example, the defaults for the C compiler would be cc.defaults
If a defaults file for the compiler is found in the directories listed in SPRO_DEFAULTS_PATH, the compiler will read the file and process the options prior to processing the options on the command line. The first defaults file found will be used and the search terminated.
System administrators may create system-wide default files in Studio-install-path/lib/compilers/etc/config. If the environment variable is set, the installed defaults file will not be read.
The format of a defaults file is similar to the command line. Each line of the file may contain one or more compiler options separated by white space. Shell expansions, such as wild cards and substitutions, will not be applied to the options in the defaults file.
The value of the SPRO_DEFAULTS_PATH and the fully expanded command line will be displayed in the verbose output produced by options —#, —###, and —dryrun.
Options specified by the user on the command line will usually override options read from the defaults file. For example, if the defaults file specifies compiling with —xO4 and the user specifies —xO2 on the command line, —xO2 will be used.
Some options appearing in the default options file will be appended after the options specified on the command line. These are the preprocessor option —I, linker options —B, —L, —R, and —l, and all file arguments, such as source files, object files, archives, and shared objects.
The following is an example of how a user-supplied default compiler option startup file might be used.
demo% cat /project/defaults/cc.defaults -I/project/src/hdrs —L/project/libs —llibproj —xvpara demo% setenv SPRO_DEFAULTS_PATH /project/defaults demo% cc —c —I/local/hdrs —L/local/libs —lliblocal tst.c
This command is now equivalent to:
cc -fast —xvpara —c —I/local/hdrs —L/local/libs —lliblocal tst.c \ —I/project/src/hdrs —L/project/libs —llibproj
While the compiler defaults file provides a convenient way to set the defaults for an entire project, it can become the cause of hard to diagnose problems. Set the environment variable SPRO_DEFAULTS_PATH to an absolute path rather than the current directory to avoid such problems.
The interface stability of the default options file is uncommitted. The order of option processing is subject to change in a future release.