C H A P T E R 3 |
Fortran Compiler Options |
This chapter details the command-line options for the f95 compiler.
The general syntax of the compiler command line is:
f95 [options] list_of_files additional_options |
Items in square brackets indicate optional parameters. The brackets are not part of the command. The options are a list of option keywords prefixed by dash (-). Some keyword options take the next item in the list as an argument. The list_of_files is a list of source, object, or library file names separated by blanks. Also, there are some options that must appear after the list of source files, and these could include additional lists of files (for example, -B, -l, and -L).
Typical compiler option formats are:
The following typographical conventions are used when describing the individual options:
Brackets, pipe, and ellipsis are meta characters used in the descriptions of the options and are not part of the options themselves.
Some general guidelines for options are:
Source files, object files, and libraries are compiled and linked in the order in which they appear on the command line.
In this section, the compiler options are grouped by function to provide an easy reference. The details will be found on the pages in the following sections, as indicated.
The following table summarizes the f95 compiler options by functionality. The table does not include obsolete and legacy option flags. Some flags serve more than one purpose and appear more than once.
The compiler has many features that are selectable by optional command-line parameters. The short list below of commonly used options is a good place to start.
Some option flags are macros that expand into a specific set of other flags. These are provided as a convenient way to specify a number of options that are usually expressed together to select a certain feature.
-xO5 -libmil -fsimple=2 -dalign -xlibmopt -depend -fns -ftrap=common -pad=local -xvector=yes -xprefetch=yes |
|
Settings that follow the macro flag on the command line override the expansion of the macro. For example, to use -fast but with an optimization level of -O3, the -O3 must come after -fast on the command line.
The following options are provided for backward compatibility with earlier compiler releases, and certain Fortran legacy capabilities.
Treat hollerith constant as character or typeless in call argument lists. |
|
Use of these option flags is not recommended for producing portable Fortran 95 programs.
The following options are considered obsolete and should not be used. They might be removed from later releases of the compiler.
Profiling. Use -pg or the Forte Developer Performance Analyzer |
|
This section shows all the f95 compiler command-line option flags, including various risks, restrictions, caveats, interactions, examples, and other details.
This options reference details each option flag.
Profile by basic block using tcov, old style. (Obsolete)
This is the old style of basic block profiling for tcov. See -xprofile=tcov for information on the new style of profiling and the tcov(1) man page for more details. Also see the Forte Developer manual, Program Performance Analysis Tools.
Specify the alignment of data in common blocks and numeric sequence types.
n may be 1, 2, 4, 8, or 16, and indicates the maximum alignment (in bytes) for data elements within common blocks and numeric sequence types.
For example, -aligncommon=4 would align data elements with natural alignments of 4 bytes or more on 4-byte boundaries.
This option does not affect data with natural alignment smaller than the specified size.
Without -aligncommon, the compiler aligns elements in common blocks and numeric sequence types on (at most) 4-byte boundaries.
Specifying -aligncommon without a value defaults to 1: all common block and numeric sequence type elements align on byte boundaries (no padding between elements).
-aligncommon=16 reverts to -aligncommon=8 on platforms that are not 64-bit enabled (platforms other than v9, v9a, or v9b).
Identify many nonstandard extensions.
Warning messages are issued for any uses of non-standard Fortran 95 extensions in the source code.
Enable automatic loop parallelization.
Finds and parallelizes appropriate loops for running in parallel on multiple processors. Analyzes loops for inter-iteration data dependencies and loop restructuring. If the optimization level is not specified -O3 or higher, it will automatically be raised to -O3.
Also specify the -stackvar option when using any of the parallelization options, including -autopar.
Avoid -autopar if the program already contains explicit calls to the libthread threads library. See note in -mt.
The -autopar option is not appropriate on a single-processor system, and the compiled code will generally run slower.
To run a parallelized program in a multithreaded environment, you must set the PARALLEL (or OMP_NUM_THREADS) environment variable prior to execution. This tells the runtime system the maximum number of threads the program can create. The default is 1. In general, set the PARALLEL or OMP_NUM_THREADS variable to the available number of processors on the target platform.
If you use -autopar and compile and link in one step, the multithreading library and the thread-safe Fortran runtime library will automatically be linked. If you use -autopar and compile and link in separate steps, then you must also link with -autopar to insure linking the appropriate libraries.
The -reduction option may also be useful with -autopar. Other parallelization options are -parallel and -explicitpar.
Refer to the Fortran Programming Guide for more information on parallelization.
Prefer dynamic or require static library linking.
No space is allowed between -B and dynamic or static. The default, without -B specified, is -Bdynamic.
You can toggle -Bstatic and -Bdynamic on the command line. That is, you can link some libraries statically and some dynamically by specifying -Bstatic and -Bdynamic any number of times on the command line, as follows:
f95 prog.f -Bdynamic -lwells -Bstatic -lsurface |
These are loader and linker options. Compiling and linking in separate steps with -Bx on the compile command will require it in the link step as well.
You cannot specify both -Bdynamic and -dn on the command line because -dn disables linking of dynamic libraries.
In a 64-bit Solaris environment, many system libraries are available only as shared dynamic libraries. These include libm.so and libc.so (libm.a and libc.a are not provided). This means that -Bstatic and -dn may cause linking errors in 64-bit Solaris environments. Applications must link with the dynamic libraries in these cases.
See the Fortran Programming Guide for more information on static and dynamic libraries.
Check array references for out of range subscripts and conformance at runtime.
Subscripting arrays beyond their declared sizes may result in unexpected results, including segmentation faults. The -C option checks for possible array subscript violations in the source code and during execution. -C also adds runtime checks for array conformance in array syntax expressions
Specifying -C may make the executable file larger.
If the -C option is used, array subscript violations are treated as an error. If an array subscript range violation is detected in the source code during compilation, it is treated as a compilation error.
If an array subscript violation can only be determined at runtime, the compiler generates range-checking code into the executable program. This may cause an increase in execution time. As a result, it is appropriate to enable full array subscript checking while developing and debugging a program, then recompiling the final production executable without subscript checking.
Compile only; produce object .o files, but suppress linking.
Compile a .o file for each source file. If only a single source file is being compiled, the -o option can be used to specify the name of the .o file written.
Compile for generic SPARC architecture. (Obsolete)
This option is a macro for: -xarch=v7 -xchip=old -xcache=64/32/1 which is equivalent to -xtarget=ss2.
Compile for SPARC V8 architecture. (Obsolete)
This option is a macro for:
-xarch=v8 -xchip=super -xcache=16/32/4:1024/32/1 which is equivalent to -xtarget=ss1000.
Allow assignment to constant arguments.
Allow a subprogram to change a dummy argument that is a constant. This option is provided only to allow legacy code to compile and execute without a runtime error.
Code that aborts unless compiled with -copyargs is, of course, not Fortran standard compliant. Also, such code is often unpredictable.
Define symbol name for the preprocessor.
This option only applies to .F, .F90, and .F95 source files.
-Dname=def Define name to have value def
On the command line, this option will define name as if:
had appears in the source file. If no =def specified, the name name is defined as the value 1. The macro symbol name is passed on to the preprocessor fpp (or cpp -- see the -xpp option) for expansion.
The predefined macro symbols have two leading underscores. The Fortran syntax may not support the actual values of these macros--they should appear only in fpp or cpp preprocessor directives.
f95 uses the fpp(1) preprocessor by default. Like the C preprocessor cpp(1), fpp expands source code macros and enables conditional compilation of code. Unlike cpp, fpp understands Fortran syntax, and is preferred as a Fortran preprocessor. Use the -xpp=cpp flag to force the compiler to specifically use cpp rather than fpp.
Align COMMON blocks and numerical sequence types, and generate faster multi-word load/stores.
This flag changes the data layout in COMMON blocks, numeric sequence types, and EQUIVALENCE classes, and enables the compiler to generate faster multi-word load/stores for that data.
The data layout effect is that of the -f flag: double- and quad-precision data in COMMON blocks and EQUIVALENCE classes are laid out in memory along their "natural" alignment, which is on 8-byte boundaries (or on 16-byte boundaries for quad-precision when compiling for 64-bit environments with -xarch=v9 or v9a). The default alignment of data in COMMON blocks is on 4-byte boundaries. The compiler is also allowed to assume natural alignment and generate faster multi-word load/stores to reference the data.
Note - -dalign may result in nonstandard alignment of data, which could cause problems with variables in EQUIVALENCE or COMMON and may render the program non-portable if -dalign is required. |
-dalign is a macro equivalent to: -xmemalign=8s -aligncommon=16. See -aligncommon[=n], and -xmemalign[=<a><b>].
If you compile one subprogram with -dalign, compile all subprograms of the program with -dalign. This option is included in the -fast option.
Note that because -dalign invokes -aligncommon, numeric sequence types are also affected by this option.
Force alignment of data on 8-byte boundaries
The value is either yes or no. If yes, all variables will be aligned on 8-byte boundaries. Default is -dbl_align_all=no.
When compiling for 64-bit environments with -xarch=v9 or v9a, this flag will align quad-precision data on 16-byte boundaries.
This flag does not alter the layout of data in COMMON blocks or user-defined structures.
Use with -dalign to enable added efficiency with multi-word load/stores.
If used, all routines must be compiled with this flag.
Analyze loops for data dependencies and do loop restructuring.
This option will raise the optimization level to O3 if no optimization level is specified, or if it is specified less than O3. -depend is also included with -fast, -autopar and -parallel. (See the Fortran Programming Guide.)
Disallow dynamic libraries. See -d{y|n}.
Show commands built by the f95 command-line driver, but do not compile.
Useful when debugging, this option displays the commands and suboptions the compiler will invoke to perform the compilation.
Allow or disallow dynamic libraries for the entire executable.
The default, if not specified, is -dy.
Unlike -Bx, this option applies to the whole executable and need appear only once on the command line.
-dy|-dn are loader and linker options. If you compile and link in separate steps with these options, then you need the same option in the link step.
In a 64-bit Solaris environment, many system libraries are not available only as shared dynamic libraries. These include libm.so and libc.so (libm.a and libc.a are not provided). This means that -dn and -Bstatic may cause linking errors in 64-bit Solaris environments. Applications must link with the dynamic libraries in these cases.
Accept extended length input source line.
Extended source lines can be up to 132 characters long. The compiler pads on the right with trailing blanks to column 132. If you use continuation lines while compiling with -e, then do not split character constants across lines, otherwise, unnecessary blanks may be inserted in the constants.
Suppress warning messages listed by tag name.
Suppress the display of warning messages specified in the comma-separated list of tag names taglist. If taglist consists of %none, no warnings are suppressed. If taglist consists of %all, all warnings are suppressed (this is equivalent to the -w option.)
f95 -erroff=WDECL_LOCAL_NOTUSED ink.f
Use the -errtags option to see the tag names associated with warning messages.
Display the message tag with each warning message.
With-errtags=yes, the compiler's internal error tag name will appear along with warning messages. The default is not to display the tag (-errtags=no).
demo% f95 -errtags ink.f ink.f: MAIN: "ink.f", line 11: Warning: local variable "i" never used (WDECL_LOCAL_NOTUSED) <- The warning message's tag name |
-errtags alone stands for -errtags=yes.
Parallelize loops or regions explicitly marked by Sun, Cray, and/or OpenMP directives.
The compiler will generate parallel code even if there are data dependencies in the DO loop that would cause the loop to generate incorrect results when run in parallel. With explicit parallelization, it is the user's responsibility to correctly analyze loops for data dependency problems before marking them with parallelization directives.
Parallelization is appropriate only on multiprocessor systems.
This option enables Sun, Cray, and/or OpenMP explicit parallelization directives. DO loops immediately preceded by parallelization directives will have threaded code generated for them.
(Use the -openmp flag, which is a macro flag that includes -explicitpar, to enable OpenMP explicit parallelization directives.See -openmp)
Note - -explicitpar should not be used to compile programs that already do their own multithreading with calls to the libthread library. |
To run a parallelized program in a multithreaded environment, you must set the PARALLEL (or OMP_NUM_THREADS) environment variable prior to execution. This tells the runtime system the maximum number of threads the program can create. The default is 1. In general, set the PARALLEL or OMP_NUM_THREADS variable to the available number of processors on the target platform.
If you use -explicitpar and compile and link in one step, then linking automatically includes the multithreading library and the thread-safe Fortran runtime library. If you use -explicitpar and compile and link in separate steps, then you must also link with -explicitpar.
To improve performance, also specify the -stackvar option when using any of the parallelization options, including -explicitpar.
Use the -mp option (-mp={%none|sun|cray|openmp}) to select the style of parallelization directives enabled: Sun, Cray, or OpenMP.
If the optimization level is not -O3 or higher, it is raised to -O3 automatically.
For details, see the "Parallelization" chapter in the Fortran Programming Guide.
Create external names with or without trailing underscores.
e must be either plain or underscores. The default is underscores.
-ext_names=plain: Do not add trailing underscore.
-ext_names=underscores: Add trailing underscore.
An external name is a name of a subroutine, function, block data subprogram, or labeled common. This option affects both the name of the routine's entry point and the name used in calls to it. Use this flag to allow Fortran 95 routines to call (and be called by) other programming language routines.
Invoke the source file preprocessor, but do not compile.
Apply the fpp preprocessor to .F files (and .f95 files with f95) and write the processed result on a file with the same name but with suffix changed to .f (or .f95), but do not compile.
writes the processed source file to source.f
fpp is the default preprocessor for Fortran. The C preprocessor, cpp, can be selected instead by specifying -xpp=cpp.
Align double- and quad-precision data in COMMON blocks.
-f is a legacy option flag equivalent to -aligncommon=16. Use of -aligncommon is preferred.
The default alignment of data in COMMON blocks is on 4-byte boundaries. -f changes the data layout of double- and quad-precision data in COMMON blocks and EQUIVALENCE classes to be placed in memory along their "natural" alignment, which is on 8-byte boundaries (or on 16-byte boundaries for quad-precision when compiling for 64-bit environments with -xarch=v9 or v9a).
Note - -f may result in nonstandard alignment of data, which could cause problems with variables in EQUIVALENCE or COMMON and may render the program non-portable if -f is required. |
Compiling any part of a program with -f requires compiling all subprograms of that program with -f.
By itself, this option does not enable the compiler to generate faster multi-word fetch/store instructions on double and quad precision data. The -dalign option does this and invokes -f as well. Use of -dalign is preferred over the older -f. See -dalign. Because -dalign is part of the -fast option, so is -f.
Select Fortran 77 compatibility mode.
This option flag enables porting legacy Fortran 77 source programs, including those with language extensions accepted by the f77 compiler, to the f95 Fortran 95 compiler.
list is a comma-separated list selected from the following possible keywords:
All keywords can be prefixed by no% to disable the feature, as in:
The default, when -f77 is not specified, is -f77=%none. Using -f77 without a list is equivalent to specifying -f77=%all.
See Chapter 5 for complete information on f77 compatibility and Fortran 77 to Fortran 95 migration.
Select options that optimize execution performance.
-fast provides high performance for certain benchmark applications. However, the particular choice of options may or may not be appropriate for your application. Use -fast as a good starting point for compiling your application for best performance. But additional tuning may still be required. If your program behaves improperly when compiled with -fast, look closely at the individual options that make up -fast and invoke only those appropriate to your program that preserve correct behavior.
Note also that a program compiled with -fast may show good performance and accurate results with some data sets, but not with others. Avoid compiling with -fast those programs that depend on particular properties of floating-point arithmetic.
Because some of the options selected by -fast have linking implications, if you compile and link in separate steps be sure to link with -fast also.
-fast selects the following options:
Details about the options selected by -fast:
It is possible to add or subtract from this list by following the -fast option with other options, as in:
f95 -fast -fsimple=1 -xnolibmopt ...
which overrides the -fsimple=2 option and disables the -xlibmopt selected by -fast.
Because -fast invokes -dalign, -fns, -fsimple=2, programs compiled with -fast can result in nonstandard floating-point arithmetic, nonstandard alignment of data, and nonstandard ordering of expression evaluation. These selections might not be appropriate for most programs.
Note that the set of options selected by the -fast flag can change with each compiler release.
Specify fixed-format Fortran 95 source input files.
All source files on the command-line will be interpreted as fixed format regardless of filename extension. Normally, f95 interprets only .f files as fixed format, .f95 as free format.
Initialize floating-point hardware to non-standard preferences.
This option is a macro for the combination of the following option flags:
Specifying -fnonstd is approximately equivalent to the following two calls at the beginning of a Fortran main program.
i=ieee_handler("set", "common", SIGFPE_ABORT) call nonstandard_arithmetic() |
The nonstandard_arithmetic() routine replaces the obsolete abrupt_underflow() routine of earlier releases.
To be effective, the main program must be compiled with this option.
Using this option initializes the floating-point hardware to:
See -fns for more information about gradual underflow and subnormal numbers.
The -fnonstd option allows hardware traps to be enabled for floating-point overflow, division by zero, and invalid operation exceptions. These are converted into SIGFPE signals, and if the program has no SIGFPE handler, it terminates with a dump of memory.
For more information, see the ieee_handler(3m) and ieee_functions(3m) man pages, the Numerical Computation Guide, and the Fortran Programming Guide.
Select SPARC nonstandard floating-point mode.
The default is the SPARC standard floating-point mode (-fns=no). (See the "Floating-Point Arithmetic" chapter of the Fortran Programming Guide.)
Optional use of =yes or =no provides a way of toggling the -fns flag following some other macro flag that includes it, such as -fast. -fns is the same as -fns=yes.
This option flag enables nonstandard floating-point mode when the program begins execution. On some SPARC systems, specifying 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 silently replaced 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.
Where x does not cause total underflow, x is a subnormal number if and only if |x| is in one of the ranges indicated:
See the Numerical Computation Guide for details on subnormal numbers, and the Fortran Programming Guide chapter "Floating-Point Arithmetic" for more information about this and similar options. (Some arithmeticians use the term denormalized number for subnormal number.)
The standard initialization of floating-point preferences is the default:
To be effective, the main program must be compiled with this option.
Detect floating-point overflow in formatted input.
With -fpover=yes specified, the I/O library will detect runtime floating-point overflows in formatted input and return an error condition (1031). The default is no such overflow detection (-fpover=no). -fpover is equivalent to -fpover=yes.
Force preprocessing of input with fpp.
Pass all the input source files listed on the f95 command line through the fpp preprocessor, regardless of file extension. (Normally, only files with .F, .F90, or .F95 extension are automatically preprocessed by fpp.) See also -xpp={fpp|cpp}.
Specify free-format source input files.
All source files on the command-line will be interpreted as f95 free format regardless of filename extension. Normally, f95 interprets .f files as fixed format, .f95 as free format.
Set the IEEE rounding mode in effect at startup.
r must be one of: nearest, tozero, negative, positive.
The default is -fround=nearest.
To be effective, compile the main program with this option.
This option sets the IEEE 754 rounding mode that:
When r is tozero, negative, or positive, the option sets the rounding direction to round-to-zero, round-to-negative-infinity, or round-to-positive-infinity, respectively, when the program begins execution. When -fround is not specified, -fround=nearest is used as the default and the rounding direction is round-to-nearest. The meanings are the same as those for the ieee_flags function. (See the "Floating-Point Arithmetic" chapter of the Fortran Programming Guide.)
Select floating-point optimization preferences.
Allow the optimizer to make simplifying assumptions concerning floating-point arithmetic. (See the "Floating-Point Arithmetic" chapter of the Fortran Programming Guide.)
For consistent results, compile all units of a program with the same -fsimple option.
If n is present, it must be 0, 1, or 2. The defaults are:
The different floating-point simplification levels are:
Set floating-point trapping mode in effect at startup.
t is a comma-separated list that consists of one or more of the following:
%all, %none, common, [no%]invalid, [no%]overflow, [no%]underflow, [no%]division, [no%]inexact.
-ftrap=common is a macro for
-ftrap=invalid,overflow,underflow,division.
The f95 default is -ftrap=common.
This option sets the IEEE 754 trapping modes that are established at program initialization. Processing is left-to-right. The common exceptions, by definition, are invalid, division by zero, and overflow. For example: -ftrap=overflow.
Example: -ftrap=%all,no%inexact means set all traps, except inexact.
The meanings for -ftrap=t are the same as for ieee_flags(), except that:
To be effective, compile the main program with this option.
For further information, see the "Floating-Point Arithmetic" chapter in the Fortran Programming Guide.
Build a dynamic shared library instead of an executable file.
Direct the linker to build a shared dynamic library. Without -G, the linker builds an executable file. With -G, it builds a dynamic library. Use -o with -G to specify the name of the file to be written. See the Fortran Programming Guide chapter "Libraries" for details.
Compile for debugging and performance analysis.
Produce additional symbol table information for debugging with dbx(1) or the Forte Developer debugging utility and for performance analysis with the Forte Developer Performance Analyzer.
Although some debugging is possible without specifying -g, the full capabilities of dbx and debugger are only available to those compilation units compiled with -g.
Some capabilities of other options specified along with -g may be limited. See the dbx documentation for details.
The -g option makes -xildon the default incremental linker option when .o object files appear on the command line (see -xild{off|on}). That is, with -g, the compiler default behavior is to automatically invoke ild in place of ld, unless the -G option is present, or any source file is named on the command line.
To use the full capabilities of the Forte Developer 6 Performance Analyzer, compile with -g. 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 Forte Developer manual Program Performance Analysis Tools.)
The commentary messages generated with -g describe the optimizations and transformations the compiler made while compiling your program. The messages, interleaved with the source code, can be displayed by the er_src(1) command.
Note that commentary messages only appear if the compiler actually performed any optimizations. You are more likely to see commentary messages when you request high optimization levels, such as with -xO4, or -fast.
Specify the name of the generated dynamic shared library.
This option is passed on to the linker. For details, see the Solaris Linker and Libraries Guide, and the Fortran Programming Guide chapter "Libraries."
The -hname option records the name name to the shared dynamic library being created as the internal name of the library. A space between -h and name is optional (except if the library name is elp, for which the space will be needed). In general, name must be the same as what follows the -o. Use of this option is meaningless without also specifying -G.
Without the -hname option, no internal name is recorded in the library file.
If the library has an internal name, whenever an executable program referencing the library is run the runtime linker will search for a library with the same internal name in any path the linker is searching. With an internal name specified, searching for the library at runtime linking is more flexible. This option can also be used to specify versions of shared libraries.
If there is no internal name of a shared library, then the linker uses a specific path for the shared library file instead.
Display a summary list of compiler options.
See also -xhelp=h.
Add path to the INCLUDE file search path.
Insert the directory path path at the start of the INCLUDE file search path. No space is allowed between -I and path. Invalid directories are ignored with no warning message.
The include file search path is the list of directories searched for INCLUDE files--file names appearing on preprocessor #include directives, or Fortran INCLUDE statements.
Example: Search for INCLUDE files in /usr/app/include:
demo% f95 -I/usr/app/include growth.F |
Multiple -Ipath options may appear on the command line. Each adds to the top of the search path list (first path searched).
The search order for relative paths on INCLUDE or #include is:
1. The directory that contains the source file
2. The directories that are named in the -I options
3. The directories in the compiler's internal default list
Enable or disable inlining of specified routines.
Request the optimizer to inline the user-written routines named in the f1,...,fn list. Prefixing a routine name with no% disables inlining of that routine.
Inlining is an optimization technique whereby the compiler effectively replaces a subprogram reference such as a CALL or function call with the actual subprogram code itself. Inlining often provides the optimizer more opportunities to produce efficient code.
The lists are a comma-separated list of functions and subroutines. To inhibit inlining of a function, prefix its name with no%.
Example: Inline the routines xbar, zbar, vpoint:
demo% f95 -O3 -inline=xbar,zbar,vpoint *.f |
Following are the restrictions; no warnings are issued:
The appearance of -inline with -O4 disables the automatic inlining that the compiler would normally perform, unless %auto is also specified. With -O4, the compilers normally try to inline all appropriate user-written subroutines and functions. Adding -inline with -O4 may degrade performance by restricting the optimizer's inlining to only those routines in the list. In this case, use the %auto suboption to enable automatic inlining at -O4 and -O5.
demo% f95 -O4 -inline=%auto,no%zpoint *.f |
In the example above, the user has enabled -O4's automatic inlining while disabling any possible inlining of the routine zpoint() that the compiler might attempt.
Set floating-point rounding mode for formatted input/output.
Sets the ROUND= specifier globally for all formatted input/output operations.
Allowed values for mode are compatible and processor-defined.
With -iorounding=compatible, the value resulting from data conversion is the one closer to the two nearest representations, or the value away from zero if the value is halfway between them.
With -iorounding=processor-defined, the rounding mode is the processor's default mode. This is the default when -iorounding is not specified.
Obsolete synonym for -xcode=pic13.
Obsolete synonym for -xcode=pic32.
Add path to list of directory paths to search for libraries.
Adds path to the front of the list of object-library search directories. A space between -L and path is optional. This option is passed to the linker. See also -lx.
While building the executable file, ld(1) searches path for archive libraries (.a files) and shared libraries (.so files). ld searches path before searching the default directories. (See the Fortran Programming Guide chapter "Libraries" for information on library search order.) For the relative order between LD_LIBRARY_PATH and
-Lpath, see ld(1).
Note - Specifying /usr/lib or /usr/ccs/lib with -Lpath may prevent linking the unbundled libm. These directories are searched by default. |
Example: Use -Lpath to specify library search directories:
demo% f95 -L./dir1 -L./dir2 any.f |
Add library libx.a to linker's list of search libraries.
Pass -lx to the linker to specify additional libraries for ld to search for unresolved references. ld links with object library libx. If shared library libx.so is available (and -Bstatic or -dn are not specified), ld uses it, otherwise, ld uses static library libx.a. If it uses a shared library, the name is built in to a.out. No space is allowed between -l and x character strings.
Example: Link with the library libVZY:
demo% f95 any.f -lVZY |
Use -lx again to link with more libraries.
Example: Link with the libraries liby and libz:
demo% f95 any.f -ly -lz |
See also the "Libraries" chapter in the Fortran Programming Guide for information on library search paths and search order.
Inline selected libm library routines for optimization.
There are inline templates for some of the libm library routines. This option selects those inline templates that produce the fastest executable for the floating-point options and platform currently being used.
For more information, see the man pages libm_single(3F) and libm_double(3F)
Show loop parallelization results.
Show which loops were and were not parallelized with the -parallel, -autopar, or -explicitpar options. (Option -loopinfo must appear with one of these parallelization options.)
-loopinfo displays a list of messages on standard error:
Add path to directory paths searched for Fortran 95 modules. No space appears between the -M and path.
path may specify the path to a directory, a .mod precompiled module file, or .a archive file of precompiled module files. The compiler determines the type of the file by examining its contents.
.a archive files must be explicitly specified on a -M option flag to be searched for modules.
Only .mod files with the same names as the MODULE names appearing on USE statements will be searched.
If not specified, the compiler searches the current directory for module files.
See Module Files for more information about modules in Fortran 95.
Specify where the compiler will write compiled .mod MODULE files.
The compiler will write the .mod MODULE information files it compiles in the directory specified by path. The directory path can also be specified with the MODDIR environment variable. If both are specified, this option flag takes precedence.
The compiler uses the current directory as the default for writing .mod files.
See Module Files for more information about modules in Fortran 95.
Select the style for parallelization directives.
The default without specifying -mp is %none.
You can combine OpenMP directives with Sun or Cray directives in the same compilation unit. But both Sun and Cray directives cannot both be active in the same compilation unit. For example:
You must also specify -explicitpar (or -parallel) to enable parallelization. For correctness, also specify -stackvar:
When compiling for OpenMP, use the -openmp flag, which includes -mp=openmp along with other flags required by OpenMP. See -openmp.
A summary of the Sun and Cray parallelization directives appears in Appendix D in this manual. See the Fortran Programming Guide for details. See the OpenMP API User's Guide for a discussion of OpenMP directives.
Require linking to thread-safe libraries.
If you do your own low-level thread management (for example, by calling the libthread library), compiling with -mt prevents conflicts.
Use -mt if you mix Fortran with multithreaded C code that calls the libthread library. See also the Solaris Multithreaded Programming Guide.
-mt is implied automatically when using the -autopar, -explicitpar, or -parallel options.
Optimize performance for the host system. (Obsolete)
This option is a synonym for -xtarget=native. The -fast option sets -xtarget=native.
Disables automatic parallelization invoked by -autopar earlier on the command line.
Cancel any -depend appearing earlier on the command line.
Disables explicit parallelization invoked by -explicitpar earlier on the command line.
Disable linking with system libraries.
Do not automatically link with any system or language library; that is do not pass any default -lx options on to ld. The normal behavior is to link system libraries into the executables automatically, without the user specifying them on the command line.
The -nolib option makes it easier to link one of these libraries statically. The system and language libraries are required for final execution. It is your responsibility to link them in manually. This option provides you with complete control.
Link libm statically and libc dynamically with f95:
demo% f95 -nolib any.f95 -Bstatic -lm -Bdynamic -lc |
The order for the -lx options is important. Follow the order shown in the examples.
Cancel -libmil on command line.
Use this option after the -fast option to disable inlining of libm math routines:
demo% f95 -fast -nolibmil ... |
Disable -reduction on command line.
This option disables -reduction.
Do not build a runtime shared library search path into the executable.
The compiler normally builds into an executable a path that tells the runtime linker where to find the shared libraries it will need. The path is installation dependent. The -norunpath option prevents that path from being built in to the executable.
This option is helpful when libraries have been installed in some nonstandard location, and you do not wish to make the loader search down those paths when the executable is run at another site. Compare with -Rpaths.
See the Fortran Programming Guide chapter on "Libraries" for more information.
n can be 1, 2, 3, 4, or 5. No space is allowed between -O and n.
If -O[n] is not specified, only a very basic level of optimization limited to local common subexpression elimination and dead code analysis is performed. A program's performance may be significantly improved when compiled with an optimization level than without optimization. Use of -O (which sets -O3) or
-fast (which sets -O5) is recommended for most programs.
Each -On level includes the optimizations performed at the levels below it. Generally, the higher the level of optimization a program is compiled with, the better runtime performance obtained. However, higher optimization levels may result in increased compilation time and larger executable files.
Debugging with -g does not suppress -On, but -On limits -g in certain ways; see the dbx documentation.
The -O3 and -O4 options reduce the utility of debugging such that you cannot display variables from dbx, but you can still use the dbx where command to get a symbolic traceback.
If the optimizer runs out of memory, it attempts to proceed over again at a lower level of optimization, resuming compilation of subsequent routines at the original level.
For details on optimization, see the Fortran Programming Guide chapters "Performance Profiling" and "Performance and Optimization."
Provides a minimum of statement-level optimizations.
Use if higher levels result in excessive compilation time, or exceed available swap space.
Enables basic block level optimizations.
This level usually gives the smallest code size. (See also -xspace.)
-O3 is preferred over -O2 unless -O3 results in unreasonably long compilation time, exceeds swap space, or generates excessively large executable files.
Adds loop unrolling and global optimizations at the function level.
Usually -O3 generates larger executable files.
Adds automatic inlining of routines contained in the same file.
Usually -O4 generates larger executable files due to inlining.
The -g option suppresses the -O4 automatic inlining described above.
-xcrossfile increases the scope of inlining with -O4.
Attempt aggressive optimizations.
Suitable only for that small fraction of a program that uses the largest fraction of compute time. -O5's optimization algorithms take more compilation time, and may also degrade performance when applied to too large a fraction of the source program.
Optimization at this level is more likely to improve performance if done with profile feedback. See -xprofile=p.
Specify the name of the executable file to be written.
There must be a blank between -o and name. Without this option, the default is to write the executable file to a.out. When used with -c, -o specifies the target .o object file; with -G it specifies the target .so library file.
Compile DO loops so that they are executed at least once. DO loops in standard Fortran are not performed at all if the upper limit is smaller than the lower limit, unlike some legacy implementations of Fortran.
Enable explicit parallelization with Fortran 95 OpenMP Version 2.0 directives.
This option is a macro that combines these options:
OpenMP directives are summarized in the Forte Developer OpenMP API User's Guide.
To run a parallelized program in a multithreaded environment, you must set the PARALLEL (or OMP_NUM_THREADS) environment variable prior to execution. This tells the runtime system the maximum number of threads the program can create. The default is 1. In general, set the PARALLEL or OMP_NUM_THREADS variable to the available number of processors on the target platform.
OpenMP requires the definition of the preprocessor symbol _OPENMP to have the decimal value YYYYMM where YYYY and MM are the year and month designations of the version of the OpenMP Fortran API that the implementation supports.
Compile position-independent code with 32-bit addresses. (Obsolete)
-PIC is equivalent to -xcode=pic32. See -xcode=addr for more information about position-independent code.
Compile for profiling with the prof profiler. (Obsolete)
Prepare object files for profiling, see prof (1). If you compile and link in separate steps, and also compile with the -p option, then be sure to link with the -p option. -p with prof is provided mostly for compatibility with older systems. -pg profiling with gprof is possibly a better alternative. See the Fortran Programming Guide chapter on Performance Profiling for details.
Insert padding for efficient use of cache.
This option inserts padding between arrays or character variables, if they are static local and not initialized, or if they are in common blocks. The extra padding positions the data to make better use of cache. In either case, the arrays or character variables can not be equivalenced.
p, if present, must be either or both of:
The -pad[=p] option applies to items that satisfy the following criteria:
For a definition of local or static variables, see -stackvar.
Parallelize with: -autopar, -explicitpar, -depend
Parallelize loops chosen automatically by the compiler as well as explicitly specified by user supplied directives. Optimization level is automatically raised to -O3 if it is lower.
To improve performance, also specify the -stackvar option when using any of the parallelization options, including -autopar.
Use -mp={%none|sun|cray|openmp}, to select Sun, Cray, or f95 OpenMP style parallelization directives. (Note: For OpenMP parallelization use -openmp, not -parallel.)
Avoid -parallel if you do your own thread management. See -mt.
Parallelization options like -parallel are intended to produce executable programs to be run on multiprocessor systems. On a single-processor system, parallelization generally degrades performance.
To run a parallelized program in a multithreaded environment, you must set the PARALLEL (or OMP_NUM_THREADS) environment variable prior to execution. This tells the runtime system the maximum number of threads the program can create. The default is 1. In general, set the PARALLEL or OMP_NUM_THREADS variable to the available number of processors on the target platform.
If you use -parallel and compile and link in one step, then linking automatically includes the multithreading library and the thread-safe Fortran runtime library. If you use -parallel and compile and link in separate steps, then you must also link with -parallel.
See the Fortran Programming Guide chapter "Parallelization" for further information.
Compile for profiling with the gprof profiler.
Compile self-profiling code in the manner of -p, but invoke a runtime recording mechanism that keeps more extensive statistics and produces a gmon.out file when the program terminates normally. Generate an execution profile by running gprof. See the gprof(1) man page and the Fortran Programming Guide for details.
Library options must be after the .f and .o files (-pg libraries are static).
If you compile and link in separate steps, and you compile with -pg, then be sure to link with -pg.
Compile position-independent code for shared library. (Obsolete)
-pic is equivalent to -xcode=pic13. See -xcode=addr for more information on position-indepented code.
Pass the suboption list ls to the compilation phase pr.
There must be blanks separating Qoption, pr, and ls. The Q can be uppercase or lowercase. The list is a comma-delimited list of suboptions, with no blanks within the list. Each suboption must be appropriate for that program phase, and can begin with a minus sign.
This option is provided primarily for debugging the internals of the compiler by support staff. Use the LD_OPTIONS environment variable to pass options to the linker. See the chapter on linking and libraries in the Fortran Programming Guide.
Build dynamic library search paths into the executable file.
With this option, the linker, ld(1), stores a list of dynamic library search paths into the executable file.
ls is a colon-separated list of directories for library search paths. The blank between -R and ls is optional.
Multiple instances of this option are concatenated together, with each list separated by a colon.
The list is used at runtime by the runtime linker, ld.so. At runtime, dynamic libraries in the listed paths are scanned to satisfy any unresolved references.
Use this option to let users run shippable executables without a special path option to find needed dynamic libraries.
Building an executable file using -Rpaths adds directory paths to a default path, /opt/SUNWspro/lib, that is always searched last.
For more information, see the "Libraries" chapter in the Fortran Programming Guide, and the Solaris Linker and Libraries Guide.
Promote single-precision constants to REAL*8 constants.
All single-precision REAL constants are promoted to REAL*8. Double-precision (REAL*8) constants are not changed. This option only applies to constants. To promote both constants and variables, see -xtypemap=spec.
Use this option flag carefully. It could cause interface problems when a subroutine or function expecting a REAL*4 argument is called with a REAL*4 constant that gets promoted to REAL*8. It could also cause problems with programs reading unformatted data files written by an unformatted write with REAL*4 constants on the I/O list.
Recognize reduction operations in loops.
Analyze loops for reduction operations during automatic parallelization. There is potential for roundoff error with the reduction.
A reduction operation accumulates the elements of an array into a single scalar value. For example, summing the elements of a vector is a typical reduction operation. Although these operations violate the criteria for parallelizability, the compiler can recognize them and parallelize them as special cases when -reduction is specified. See the Fortran Programming Guide chapter "Parallelization" for information on reduction operations recognized by the compilers.
This option is usable only with the automatic parallelization options -autopar or -parallel. It is ignored otherwise. Explicitly parallelized loops are not analyzed for reduction operations.
Example: Automatically parallelize with reduction:
demo% f95 -parallel -reduction any.f |
Compile and only generate assembly code.
Compile the named programs and leave the assembly-language output on corresponding files suffixed with .s. No .o file is created.
Strip the symbol table out of the executable file.
This option makes the executable file smaller and more difficult to reverse engineer. However, this option inhibits debugging with dbx or other tools, and overrides -g.
Produce table information for the Forte Developer source code browser.
See Using Forte Developer for more information.
Note - -sb cannot be used on source files the compiler automatically passes through the fpp or cpp preprocessors (that is, files with .F, .F90, or .F95 extensions), or used with the -F option. |
Produce only source code browser tables.
Produce only table information for the Forte Developer source code browser. Do not assemble, link, or make object files.
Note - -sbfast cannot be used on source files the compiler automatically passes through the fpp or cpp preprocessors (that is, files with .F, .F90, or .F95 extensions), or used with the -F option. |
Normally, the f95 compiler does not issue messages, other than error diagnostics, during compilation. This option flag is provided for compatibility with the legacy f77 compiler, and its use is redundant except with the -f77 compatibility flag.
Allocate local variables on the stack whenever possible.
This option makes writing recursive and re-entrant code easier and provides the optimizer more freedom when parallelizing loops.
Use of -stackvar is recommended with any of the parallelization options.
Local variables are variables that are not dummy arguments, COMMON variables, variables inherited from an outer scope, or module variables made accessible by a USE statement.
With -stackvar in effect, local variables are allocated on the stack unless they have the attributes SAVE or STATIC. Note that explicitly initialized variables are implicitly declared with the SAVE attribute. A structure variable that is not explicitly initialized but some of whose components are initialized is, by default, not implicitly declared SAVE. Also, variables equivalenced with variables that have the SAVE or STATIC attribute are implicitly SAVE or STATIC.
A statically allocated variable is implicitly initialized to zero unless the program explicitly specifies an initial value for it. Variables allocated on the stack are not implicitly initialized except that components of structure variables can be initialized by default.
Putting large arrays onto the stack with -stackvar can overflow the stack causing segmentation faults. Increasing the stack size may be required.
The initial thread executing the program has a main stack, while each helper thread of a multithreaded program has its own thread stack.
The default stack size is about 8 Megabytes for the main stack and 4 Megabytes (8 Megabytes on SPARC V9 platforms) for each thread stack. The limit command (with no parameters) shows the current main stack size. If you get a segmentation fault using -stackvar, try increasing the main and thread stack sizes.
Example: Show the current main stack size:
demo% limit cputime unlimited filesize unlimited datasize 523256 kbytes stacksize 8192 kbytes <--- coredumpsize unlimited descriptors 64 memorysize unlimited demo% |
Example: Set the main stack size to 64 Megabytes:
demo% limit stacksize 65536 |
Example: Set each thread stack size to 8 Megabytes:
demo% setenv STACKSIZE 8192 |
For further information of the use of -stackvar with parallelization, see the "Parallelization" chapter in the Fortran Programming Guide. See csh(1) for details on the limit command.
Permit STOP statement to return an integer status value.
yn is either yes or no. The default is no.
With -stop_status=yes, a STOP statement may contain an integer constant. That value will be passed to the environment as the program terminates:
The value must be in the range 0 to 255. Larger values are truncated and a run-time message issued. Note that
is still accepted and returns a status value of 0 to the environment, although a compiler warning message will be issued.
The environment status variable is $status for the C shell csh, and $? for the Bourne and Korn shells, sh and ksh.
Define directory for temporary files.
Set directory for temporary files used by the compiler to be dir. No space is allowed within this option string. Without this option, the files are placed in the /tmp directory.
The time spent and resources used in each compiler pass is displayed.
Recognize upper and lower case in source files.
Do not treat uppercase letters as equivalent to lowercase. The default is to treat uppercase as lowercase except within character-string constants. With this option, the compiler treats Delta, DELTA, and delta as different symbols.
Portability and mixing Fortran with other languages may require use of -U. See the Fortran Programming Guide chapter on porting programs to Fortran 95.
Undefine preprocessor macro name.
This option applies only to .F and .F95 source files that invoke the fpp or cpp pre-processor. It removes any initial definition of the preprocessor macro name created by -Dname on the same command line, including those implicitly placed there by the command-line driver, regardless of the order the options appear. It has no effect on any macro definitions in source files. Multiple -Uname flags can appear on the command line. There must be no space between -U and the macro name.
Make the default type for all variables be undeclared rather than using Fortran implicit typing. This option warns of undeclared variables, and does not override any IMPLICIT statements or explicit type statements.
Enable unrolling of DO loops where possible.
n is a positive integer. The choices are:
Loop unrolling generally improves performance, but will increase the size of the executable file. For more information on this and other compiler optimizations, see the "Performance and Optimization" chapter in the Fortran Programming Guide. See also The UNROLL Directive.
list is a comma-separated list of module names or module file names.
Compiling with -use=module_name has the effect of adding a USE module_name statement to each subprogram or module being compiled. Compiling with -use=module_file_name has the effect of adding a USE module_name for each of the modules contained in the specified file.
See Module Files for more information about modules in Fortran 95.
Show name and version of each compiler pass.
This option prints the name and version of each pass as the compiler executes.
This information may be helpful when discussing problems with Sun service engineers.
Verbose mode - show details of each compiler pass.
Like -V, shows the name of each pass as the compiler executes, and details the options, macro flag expansions, and environment variables used by the driver.
Show verbose parallelization messages.
As the compiler analyzes loops explicitly marked for parallelization with directives, it issues warning messages about certain data dependencies it detects; but the loop will still be parallelized.
Example: Verbose parallelization warnings:
demo% f95 -explicitpar -vpara any.f any.f: MAIN any: "any.f", line 11: Warning: the loop may have parallelization inhibiting reference |
Show or suppress warning messages.
This option shows or suppresses most warning messages. However, if one option overrides all or part of an option earlier on the command line, you do get a warning.
-w0 shows just error messages. This is equivalent to -w
-w1 shows errors and warnings. This is the default without -w.
-w2 shows errors, warnings, and cautions.
-w3 shows errors, warnings, cautions, and notes.
-w4 shows errors, warnings, cautions, notes, and comments.
Example: -w still allows some warnings to get through:
demo% f95 -w -parallel any.f f95: Warning: Optimizer level changed from 0 to 3 to support parallelized code demo% |
Produce listings and do global program checking (GPC).
Use this option to find potential programming bugs. It invokes an extra compiler pass to check for consistency in subprogram call arguments, common blocks, and parameters, across the global program. The option also generates a line-numbered listing of the source code, including a cross reference table. The error messages issued by the -Xlist options are advisory warnings and do not prevent the program from being compiled and linked.
Note - Be sure to correct all syntax errors in the source code before compiling with -Xlist. Unpredictable reports may result when run on a source code with syntax errors. |
Example: Check across routines for consistency:
demo% f95 -Xlist fil.f |
The above example writes the following to the output file fil.lst:
By default, the listings are written to the file name.lst, where name is taken from the first listed source file on the command line.
A number of sub-options provide further flexibility in the selection of actions. These are specified by suffixes to the main -Xlist option, as shown in the following table
Show errors, listing, and cross references, but no object files |
|
See the Fortran Programming Guide chapter "Program Analysis and Debugging" for details.
Specify degree of aliasing to be assumed by the compiler.
Some non-standard programming techniques can introduce situations that interfere with the compiler's optimization strategies. The use of overindexing, pointers, and passing global or non-unique variables as subprogram arguments, can introduce ambiguous aliasing situations that could result code that does not work as expected.
Use the -xalias flag to inform the compiler about the degree to which the program deviates from the aliasing requirements of the Fortran standard.
The flag may appear with or without a list. The keywords on the list are comma-separated, and each keyword indicates an aliasing situation present in the program.
Each keyword may be prefixed by no% to indicate an aliasing type that is not present.
Specifying -xalias without a list gives the best performance for most programs that do not violate Fortran aliasing rules, and corresponds to:
To be effective, -xalias should be used when compiling with optimization levels -xO3 and higher.
The compiler default, with no -xalias flag specified, assumes that the program conforms to the Fortran 95 standard except for Cray pointers:
Examples of various aliasing situations and how to specify them with -xalias are given in the Porting chapter of the Fortran Programming Guide.
Specify instruction set architecture (ISA).
Architectures that are accepted by -xarch keyword isa are shown in TABLE 3-11:
generic, generic64, native, native64, v7, v8a, v8, v8plus, v8plusa, v8plusb, v9, v9a, v9b |
Note that although -xarch 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:
overrides the -xarch=v8 set by -xtarget=ultra2
This option limits the code generated by the compiler to the instructions of the specified instruction set architecture by allowing only the specified set of instructions. This option does not guarantee use of any target-specific instructions.
If this option is used with optimization, the appropriate choice can provide good performance of the executable on the specified architecture. An inappropriate choice results in a binary program that is not executable on the intended target platform.
TABLE 3-12 summarizes the most general -xarch options:
For any particular choice, the generated executable may run much more slowly on earlier architectures. Also, although quad-precision (REAL*16 and long double) floating-point instructions are available in many of these instruction set architectures, the compiler does not use these instructions in the code it generates.
TABLE 3-13 gives details for each of the -xarch keywords on SPARC platforms.
Define cache properties for the optimizer.
c must be one of the following:
The si/li/ai are defined as follows:
si The size of the data cache at level i, in kilobytes
li The line size of the data cache at level i, in bytes
ai The associativity of the data cache at level i
This option specifies the cache properties that the optimizer can use. It does not guarantee that any particular cache property is used.
Although this option can be used alone, it is part of the expansion of the
-xtarget option; it is provided to allow overriding an -xcache value implied by a specific -xtarget option.
Define the cache properties for good performance on most SPARC processors without any major performance degradation. This is the default. |
|
Example: -xcache=16/32/4:1024/32/1 specifies the following:
A Level 1 cache has: 16K bytes, 32 byte line size, 4-way associativity.
A Level 2 cache has: 1024K bytes, 32 byte line size, direct mapping associativity.
Generate special runtime checks.
v must be one of the following:
Turn on runtime checking for stack overflow on subprogram entry. If a stack overflow is detected, a SIGSEGV segment fault will be raised. |
|
Stack overflow is the only runtime check implemented with this flag in this release of the compiler. Stack overflows, especially in multithreaded applications with large arrays allocated on the stack, can cause silent data corruption in neighboring thread stacks. Compile all routines with -xcheck=stkovf if stack overflow is suspected. But note that compiling with this flag does not guarantee that all stack overflow situations will be detected since they could occur in routines not compiled with this flag.
Specify target processor for the optimizer.
This option specifies timing properties by specifying the target processor.
Although this option can be used alone, it is part of the expansion of the
-xtarget option; it is provided to allow overriding a -xchip value implied by the a specific -xtarget option.
The following table lists the valid -xchip values:
Specify code address space on SPARC platforms.
The defaults (not specifying -xcode=addr explicitly) are:
-xcode=abs32 on SPARC V8 and V7 platforms.
-xcode=abs64 on SPARC and UltraSPARC V9 (-xarch=v9 or v9a)
Use -xcode=pic13 or -xcode=pic32 when creating dynamic shared libraries to improve runtime performance.
While the code within a dynamic executable is usually tied to a fixed address in memory, position-independent code can be loaded anywhere in the address space of the process.
When you use position-independent code, relocatable references are generated as an indirect reference through a global offset table. Frequently accessed items in a shared object will benefit from compiling with -xcode=pic13 or -xcode=pic32 by not requiring the large number of relocations imposed by code that is not position-independent.
The size of the global offset table is limited to 8Kb.
There are two nominal performance costs with -xcode={pic13|pic32} :
When considering the above costs, remember that the use of -xcode=pic13 or -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 or not a .o file has been compiled with -xcode=pic13 or -xcode=pic32 is with the nm command:
A .o file containing position-independent code will contain an unresolved external reference to _GLOBAL_OFFSET_TABLE_ as marked by the letter U.
To determine whether to use -xcode=pic13 or -xcode=pic32 use nm to identify the number of distinct global and static variables used or defined in the library. If the size of _GLOBAL_OFFSET_TABLE_ is under 8,192 bytes, you can use pic13. Otherwise, you must use pic32.
Compiling with the -xcode=pic13 or pic32 (or -pic or -PIC) options is recommended when building dynamic libraries. See the Solaris Linker and Libraries Guide.
Enable runtime checking of common block inconsistencies.
This option provides a debug check for common block inconsistencies in programs using TASK COMMON and parallelization. (See the discussion of the TASK COMMON directive in the "Parallelization" chapter in the Fortran Programming Guide.)
The default is -xcommonchk=no; runtime checking for common block inconsistencies is disabled because it will degrade performance. Use -xcommon=yes only during program development and debugging, and not for production-quality programs.
Compiling with -xcommonchk=yes enables runtime checking. If a common block declared in one source program unit as a regular common block appears somewhere else on a TASK COMMON directive, the program will stop with an error message indicating the first such inconsistency.
Example: Missing TASKCOMMON directive in tc.f
Enable optimization and inlining across source files.
If specified, n may be 0, or 1.
Normally, the scope of the compiler's analysis is limited to each separate file on the command line. For example, -O4's automatic inlining is limited to subprograms defined and referenced within the same source file.
With -xcrossfile, the compiler analyzes all the files named on the command line as if they had been concatenated into a single source file.
-xcrossfile is only effective when used with -O4 or -O5.
Cross-file inlining creates a possible source file interdependence that would not normally be there. If any file in a set of files compiled together with
-xcrossfile is changed, then all files must be recompiled to insure that the new code is properly inlined. See -inline=[%auto][[,][no%]f1,...[no%]fn].
The default, without -xcrossfile on the command line, is -xcrossfile=0, and no cross-file optimizations are performed. To enable cross-file optimizations, specify -xcrossfile (equivalent to -xcrossfile=1).
Allow function-level reordering by the Forte Developer Performance Analyzer.
Allow the reordering of functions (subprograms) in the core image using the compiler, the performance analyzer and the linker. If you compile with the -xF option, then run the analyzer, you can generate a map file that optimizes the ordering of the functions in memory depending on how they are used together. A subsequent link to build the executable file can be directed to use that map by using the linker -Mmapfile option. It places each function from the executable file into a separate section.
Reordering the subprograms in memory is useful only when the application text page fault time is consuming a large percentage of the application time. Otherwise, reordering may not improve the overall performance of the application. See the Forte Developer Program Performance Analysis Tools manual for further information on the analyzer.
Treat Hollerith constant as a character string in an actual argument list.
With -xhasc=yes, the compiler treats Hollerith constants as character strings when they appear as an actual argument on a subroutine or function call. This is the default, and complies with the Fortran standard. (The actual call list generated by the compiler contains hidden string lengths for each character string.)
With -xhasc=no, Hollerith constants are treated as typeless values in subprogram calls, and only their addresses are put on the actual argument list. (No string length is generated on the actual call list passed to the subprogram.)
Compile routines with -xhasc=no if they call a subprogram with a Hollerith constant and the called subprogram expects that argument as INTEGER (or anything other than CHARACTER).
Passing 4habcd to z is handled correctly by compiling with -xhasc=no.
This flag is provided to aid porting legacy Fortran 77 programs.
Show summary help information on options or README file.
The h is either readme or flags.
-xhelp=readme Show the online README file for this release of the compiler.
-xhelp=flags Show the compiler flags (options), and is same as -help.
Enable interval arithmetic extensions and set a suitable floating-point environment.
v can be one of either widestneed or strict. The default if not specified is widestneed.
Fortran 95 extensions for interval arithmetic calculations are detailed in the Interval Arithmetic Programming Reference. See also -xinterval[=v].
The -xia flag is a macro that expands as follows:
Enable/disable the Incremental Linker.
-xildoff disables the use of the incremental linker, ild. The standard linker, ld, is used instead. -xildon enables use of ild instead of ld.
-xildoff is the default if you do not use the -g option. It is also the default if you use -G or name any source file on the command line.
-xildon is the default if you use -g and do not use -G, and no source files appear on the command line (just object files and/or libraries).
See the section on ild in the C User's Guide.
Enable interval arithmetic extensions.
v can be one of either no, widestneed or strict. The default if not specified is widestneed.
Fortran 95 extensions for interval arithmetic calculations are detailed in the Fortran 95 Interval Arithmetic Programming Reference. See also -xia[=v].
Perform interprocedural optimizations.
Performs whole-program optimizations by invoking an interprocedural analysis pass. Unlike -xcrossfile, -xipo will perform optimizations across all object files in the link step, and is not limited to just the source files on the compile command.
-xipo is particularly useful when compiling and linking large multi-file applications. Object files compiled with this flag have analysis information compiled within them that enables interprocedural analysis across source and pre-compiled program files. However, analysis and optimization is limited to the object files compiled with -xipo, and does not extend to object files on libraries.
-xipo=0 disables, and -xipo=1 enables, interprocedural analysis. -xipo=2 adds interprocedural aliasing analysis and memory allocation and layout optimizations to improve cache performance. The default is -xipo=0, and if -xipo is specified without a value, -xipo=1 is used.
When compiling and linking are performed in separate steps, -xipo must be specified in both steps to be effective.
Example using -xipo in a single compile/link step:
demo% f95 -xipo -xO4 -o prog part1.f part2.f part3.f |
The optimizer performs crossfile inlining across all three source files. This is done in the final link step, so the compilation of the source files need not all take place in a single compilation and could be over a number of separate compilations, each specifying -xipo.
Example using -xipo in separate compile/link steps:
demo% f95 -xipo -xO4 -c part1.f part2.f demo% f95 -xipo -xO4 -c part3.f demo% f95 -xipo -xO4 -o prog part1.o part2.o part3.o |
The object files created in the compile steps have additional analysis information compiled within them to permit crossfile optimizations to take place at the link step.
A restriction is that libraries, even if compiled with -xipo do not participate in crossfile interprocedural analysis, as shown in this example:
demo% f95 -xipo -xO4 one.f two.f three.f demo% ar -r mylib.a one.o two.o three.o ... demo% f95 -xipo -xO4 -o myprog main.f four.f mylib.a |
Here interprocedural optimizations will be performed between one.f, two.f and three.f, and between main.f and four.f, but not between main.f or four.f and the routines on mylib.a. (The first compilation may generate warnings about undefined symbols, but the interprocedural optimizations will be performed because it is a compile and link step.)
Other important information about -xipo:
Recognize calls to a known library.
When specified, the compiler treats references to certain known libraries as intrinsics, ignoring any user-supplied versions. This enables the compiler to perform optimizations over calls to library routines based on its special knowledge of that library.
The known libraries are limited currently to blas and intrinsics:
Prepare for linking with runtime libraries compiled with earlier versions of f77.
f95 -xlang=f77 implies linking with the f77compat library, and is a shorthand way for linking Fortran 95 object files with older Fortran 77 object files. Compiling with this flag insures the proper runtime environment.
Use f95 -xlang=f77 when linking f95 and f77 compiled objects together into a single executable.
Use library of optimized math routines.
Use selected math routines optimized for speed. This option usually generates faster code. It may produce slightly different results; if so, they usually differ in the last bit. The order on the command line for this library option is not significant.
Link with the Sun Performance Library.
f95 -o pgx -fast pgx.f -xlic_lib=sunperf |
As with -l, this option should appear on the command line after all source and object file names.
This option must be used to link with the Sun Performance Library. (See the Sun Performance Library User's Guide.)
Use this option to return serial number entitlement information about the installed Forte Developer software.
Enable optimization pragma and set maximum optimization level.
n has the value 1 through 5 and corresponds to the optimization levels of -O1 through -O5. If not specified, the compiler uses 5.
This option enables the C$PRAGMA SUN OPT=n directive when it appears in the source input. Without this option, the compiler treats these lines as comments. See The OPT Directive.
If this pragma appears with an optimization level greater than the maximum level on the -xmaxopt flag, the compiler uses the level set by -xmaxopt.
Specify maximum assumed memory alignment and behavior of misaligned data accesses.
For memory accesses where the alignment is determinable at compile time, the compiler will generate the appropriate load/store instruction sequence for that data alignment.
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 flag allows the user to specify the maximum memory alignment of data to be assumed by the compiler for those indeterminate situations. It also specifies the error behavior at runtime when a misaligned memory access does take place.
The value specified consists of two parts: a numeric alignment value, <a>, and an alphabetic behavior flag, <b>.
Allowed values for alignment, <a>, are:
Allowed values for error behavior on accessing misaligned data, <b>, are:
The defaults without -xmemalign specified are:
The default for -xmemalign appearing without a value is 1i for all platforms.
The -dalign option is a macro:
Use with -fast to override linking the optimized math library:
Select source file preprocessor.
The compilers use fpp(1) to preprocess .F or .f95 source files. This preprocessor is appropriate for Fortran. Previous versions used the standard C preprocessor cpp. To select cpp, specify -xpp=cpp.
Enable prefetch instructions on those architectures that support prefetch, such as UltraSPARC II or UltraSPARC III (-xarch=v8plus, v8plusa, v9plusb, v9, v9a, or v9b)
See The PREFETCH Directives for a description of the Fortran PREFETCH directives.
a must be one of the following:
Adjust the compiler's assumed prefetch-to-load and prefetch-to-store latencies by the specified factor. The factor must be a positive floating-point or integer number. |
|
With -xprefetch, -xprefetch=auto, and -xprefetch=yes, the compiler is free to insert prefetch instructions into the code it generates. This may result in a performance improvement on architectures that support prefetch.
If you are running computationally intensive codes on large multiprocessors, you might find it advantageous to use -xprefetch=latx:factor. This option instructs the code generator to adjust the default latency time between a prefetch and its associated load or store by the specified factor.
The prefetch latency is the hardware delay between the execution of a prefetch instruction and the time the data being prefetched is available in the cache. The compiler assumes a prefetch latency value when determining how far apart to place a prefetch instruction and the load or store instruction that uses the prefetched data.
Note - The assumed latency between a prefetch and a load may not be the same as the assumed latency between a prefetch and a store. |
The compiler tunes the prefetch mechanism for optimal performance across a wide range of machines and applications. This tuning may not always be optimal. For memory-intensive applications, especially applications intended to run on large multiprocessors, you may be able to obtain better performance by increasing the prefetch latency values. To increase the values, use a factor that is greater than 1. A value between .5 and 2.0 will most likely provide the maximum performance.
For applications with datasets that reside entirely within the external cache, you may be able to obtain better performance by decreasing the prefetch latency values. To decrease the values, use a factor that is less than 1.
To use the -xprefetch=latx:factor option, start with a factor value near 1.0 and run performance tests against the application. Then increase or decrease the factor, as appropriate, and run the performance tests again. Continue adjusting the factor and running the performance tests until you achieve optimum performance. When you increase or decrease the factor in small steps, you will see no performance difference for a few steps, then a sudden difference, then it will level off again.
If -xprefetch is not specified, -xprefetch=no%auto,explicit is assumed.
If only -xprefetch is specified, -xprefetch=auto,explicit is assumed.
The default of no%auto is assumed unless explicitly overridden with the use of -xprefetch without any arguments or with an argument of auto or yes. For example, -xprefetch=explicit is the same as -xprefetch=explicit,no%auto.
The default of explicit is assumed unless explicitly overridden with an argument of no%explicit or an argument of no. For example, -xprefetch=auto is the same as -xprefetch=auto,explicit.
If automatic prefetching is enabled, such as with -xprefetch or -xprefetch=yes, but a latency factor is not specified, then -xprefetch=latx:1.0 is assumed.
With -xprefetch=explicit, the compiler will recognize the directives:
The -xchip setting effects the determination of the assumed latencies and therefore the result of a latx:factor setting.
The latx:factor suboption is valid only when automatic prefetching is enabled. That is, latx:factor is ignored unless it is used with yes or auto.
Explicit prefetching should only be used under special circumstances that are supported by measurements.
Because the compiler tunes the prefetch mechanism for optimal performance across a wide range of machines and applications, you should only use -xprefetch=latx:factor when the performance tests indicate there is a clear benefit. The assumed prefetch latencies may change from release to release. Therefore, retesting the effect of the latency factor on performance whenever switching to a different release is highly recommended.
Control the automatic generation of prefetch instructions.
This option is only effective when compiling with:
The default for -xprefetch=auto without specifying -xprefetch_level is level 2.
Prefetch level 2 generates additional opportunities for prefetch instructions than level 1. Prefetch level 3 generates additional prefetch instructions than level 2.
Prefetch levels 2 and 3 are only effective on UltraSPARC III platforms (v8plusb or v9b)
Collect or optimize with runtime profiling data.
p must be one of collect[:name], use[:name], or tcov. Optimization level must be -O2 or greater.
Note - The report produced by tcov can be unreliable if there is inlining of subprograms due to -O4 or -inline. Coverage of calls to routines that have been inlined is not recorded. |
Allow routines without RECURSIVE attribute call themselves recursively.
Normally, only subprograms defined with the RECURSIVE attribute can call themselves recursively.
Compiling with -xrecursive enables subprograms to call themselves, even if they are not defined with the RECURSIVE attribute. But, unlike subroutines defined RECURSIVE, use of this flag does not cause local variables to be allocated on the stack by default. For local variables to have separate values in each recursive invocation of the subprogram, compile also with -stackvar to put local variables on the stack.
Compiling with -xrecursive may cause performance degradations.
r is a comma-separated list that consists of one or more of the following:
Where the % is shown, it is a required character.
The default is: -xregs=appl,float.
Allow debugging by dbx without object (.o) files.
With -xs, if you move executables to another directory, then you can use dbx and ignore the object (.o) files. Use this option when you cannot keep the .o files.
Without -xs, if you move the executables, you must move both the source files and the object (.o) files, or set the path with either the dbx pathmap or use command.
Allow the compiler to assume that no memory protection violations occur.
Using this option allows the compiler to assume no memory-based traps occur. It grants permission to use the speculative load instruction on the SPARC V9 platforms.
This option is effective only when used with optimization level -O5 one one of the following architectures (-xarch): v8plus, v8plusa, v8plusb, v9, v9a, or v9b
Do no optimizations that increase the code size.
Example: Do not unroll or parallelize loops if it increases code size.
Specify the target platform for the instruction set and optimization.
t must be one of: native, native64, generic, generic64, platform-name.
The -xtarget option permits a quick and easy specification of the -xarch, -xchip, and -xcache combinations that occur on real platforms. The only meaning of -xtarget is in its expansion.
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. This is especially true when running on the newer SPARC processors. However, for most programs and older SPARC processors, the performance gain is negligible and a generic specification is sufficient.
native: Optimize performance for the host platform.
native64: Compile for native 64-bit environment.
generic: Get the best performance for generic architecture, chip, and cache.
generic64: Compile for generic 64-bit environment.
platform-name: Get the best performance for the specified platform.
Specify default data mappings.
This option provides a flexible way to specify the byte sizes for default data types. This option applies to both default-size variables and constants.
The specification string spec may contain any or all of the following in a comma-delimited list:
The allowable combinations on each platform are:
maps both default REAL and DOUBLE to 8 bytes.
This option applies to all variables declared with default specifications (without explicit byte sizes), as in REAL XYZ (resulting in a 64-bit XYZ). Also, all single-precision REAL constants are promoted to REAL*8.
Note that INTEGER and LOGICAL are treated the same, and COMPLEX is mapped as two REALs. Also, DOUBLE COMPLEX will be treated the way DOUBLE is mapped.
Enable automatic calls to the SPARC vector library functions.
With -xvector=yes, the compiler is permitted to transform certain math library calls within DO loops into single calls to the equivalent vectorized library routine whenever possible. This could result in a performance improvement for loops with large loop counts.
The compiler defaults to -xvector=no. Specifying -xvector by itself defaults to -xvector=yes.
This option also triggers -depend. (Follow -xvector with -nodepend on the command line to cancel the dependency analysis.)
The compiler will automatically notify the linker to include the libmvec and libc libraries in the load step if -xvector appears. However, to compile and link in separate steps requires specifying -xvector on the link step as well to correctly select these necessary libraries.
Generate only pure libraries with no relocations.
The general purpose of -ztext is to verify that a generated library is pure text; instructions are all position-independent code. Therefore, it is generally used with both -G and -pic.
With -ztext, if ld finds an incomplete relocation in the text segment, then it does not build the library. If it finds one in the data segment, then it generally builds the library anyway; the data segment is writable.
Without -ztext, ld builds the library, relocations or not.
A typical use is to make a library from both source files and object files, where you do not know if the object files were made with -pic.
Example: Make library from both source and object files:
demo% f95 -G -pic -ztext -o MyLib -hMyLib a.f b.f x.o y.o |
An alternate use is to ask if the code is position-independent already: compile without -pic, but ask if it is pure text.
Example: Ask if it is pure text already--even without -pic:
demo% f95 -G -ztext -o MyLib -hMyLib a.f b.f x.o y.o |
If you compile with -ztext and ld does not build the library, then you can recompile without -ztext, and ld will build the library. The failure to build with -ztext means that one or more components of the library cannot be shared; however, maybe some of the other components can be shared. This raises questions of performance that are best left to you, the programmer.
Copyright © 2002, Sun Microsystems, Inc. All rights reserved.