This chapter contains the following topics:

• Section 2.1, f90 Command: Files and Options
• Section 2.2, Driver Programs and Passing Options to cc and ld
• Section 2.3, Compiler Limits, Diagnostic Messages, and Error Conditions
• Section 2.4, Compilation Control: Statements and Directives
• Section 2.5, Linking Object Libraries
• Section 2.6, Creating Shared Libraries

For detailed information on f90 and fort command-line options, see Chapter 3.

2.1 f90 Command: Files and Options

You should almost always use the f90 command (or fort command on Linux systems) to invoke both the Compaq Fortran compiler and the ld linker.

To link one or more object files created by the Compaq Fortran compiler, you should use the f90 command (instead of the ld command), because the f90 command automatically references the appropriate Compaq Fortran Run-Time Libraries when it invokes ld .

When you create your source files using a text editor, use file name suffix conventions expected by the f90 command, as described in Section 2.1.1.

2.1.1 File Suffixes and Source Forms

When creating a source file, choose the file name suffix appropriate for the source form (fixed or free). The f90 command recognizes certain source file suffixes as Fortran 95/90 source files.

Table 2-1 shows the recognized Fortran 95/90 source file suffixes.

Table 2-1 File Suffixes Recognized as Fortran 95/90 Source Files

Suffix	Description
.f90	Identifies Fortran 95/90 files in free source form passed to the Compaq Fortran compiler.
.F90	Identifies Fortran 95/90 files in free source form passed to the cpp preprocessor and then compiled by the Compaq Fortran compiler.
.f , .for	Identifies Fortran files in fixed (or tab) source form passed to the Compaq Fortran compiler but not preprocessed by cpp .
.F , .FOR	Identifies Fortran files in fixed (or tab) source form passed to the cpp preprocessor and then compiled by the Compaq Fortran compiler.

Except for .F , .FOR , and .F90 files, preprocessors are not automatically run before Compaq Fortran compilation. To request that the cpp preprocessor be run before compilation, specify the -cpp option.

You can specify the source file form for all Fortran files on an f90 command line by using the -free option or -fixed option.

Table 2-2 shows other file name suffixes.

Table 2-2 Other File Name Suffixes

Suffix	Description
Library and Object Files
.a	Identifies archive object libraries passed to cc , which are in turn passed to ld . All routines in the specified object library are searched during linking to resolve external references.
.o	Identifies object files passed to ld .
.so	Identifies shared object libraries passed to cc , which are in turn passed to ld . All routines in the specified object library are searched during linking to resolve external references.
Compaq Fortran Module Files
.mod	Identifies Fortran 95/90 module files created by the Compaq Fortran compiler. You do not create a .mod file directly and cannot specify a .mod file on the f90 command line (see Section 2.1.3).
Other Source Files
.c	Identifies C language source files passed to the C compiler driver cc or ccc , which performs additional command-line parsing before invoking the C preprocessor (via the command cpp ) and the C language compiler.
.i , .i90	Identifies intermediate files passed from cpp to the Compaq Fortran compiler. The .i or .i90 files are usually created by using the f90 options -p or -k (keep intermediate file) and -cpp (invoke cpp ). The .i files are assumed to be in fixed source form. The .i90 file are assumed to be in free source form.
.s	Identifies assembler files passed to cc or to ccc .

To specify libraries (in addition to those automatically searched by the f90 command), you can also use an f90 command-line option, such as -lstring .

Source file suffixes used by other Compaq languages include:

• On Tru64 UNIX and Linux: C++ ( .cxx , .cc , .c )
• On Tru64 UNIX only: Ada ( .ada ), COBOL ( .cob ), Pascal ( .p ) and PL/I ( .pli )

For More Information:

On source forms and source coding guidelines that allow the same source file to be used with multiple source forms, see the Compaq Fortran Language Reference Manual.

2.1.2 Format of the f90 and fort Commands

The f90 command (on Tru64 UNIX systems) has the following general form:

f90 [--options [args]]... filename [filename]... [--options [args]]...

The fort command (on Linux systems) has the following general form:

fort [--options [args]]... filename [filename]... [--options [args]]...

--options [args]

Indicates either special actions to be performed by the compiler or linker, or special properties of input or output files. For details about command-line options, see Chapter 3.

If you specify the -lstring option (which indicates libraries to be searched by the linker) or an object library file name, place it after the file names and after other options.

filename

Specifies the source files containing the program units to be compiled and other files to be used by the Compaq Fortran compiler. The file name has a suffix that indicates the type of file used, such as .f90 or .f (see Section 2.1.1).

If you omit the suffix or it is not one of the preceding types recognized by the f90 command, the file is assumed to be an object file and is passed directly to the linker.

An example f90 command line follows:

% f90 -v test.f calc.o -lmnd

This command specifies the following:

• The -v option displays the compilation and link passes with their arguments and files, including the libraries passed to ld .
• The file test.f is passed to the Compaq Fortran compiler for compilation. The resulting object file is passed to the linker.
• The object file calc.o is passed directly to the linker. The linker links both object files into an executable program.
• The -lmnd option specifies that the object library libmnd should be searched for unresolved global references. Note that -lmnd is placed after the file names and other options.

Compaq Fortran creates a module file for each module declaration and automatically searches for a module file referenced by a USE statement. A module file contains the equivalent of the module source declaration in a post-compiled, binary form.

2.1.3.1 Creating Module Files

When you compile a Compaq Fortran source file that contains module declarations, Compaq Fortran creates a separate file for each module declaration. The name declared in a MODULE statement becomes the base prefix of the file name and is followed by the .mod suffix.

For example, consider compiling a file that contains the following statement:

MODULE MOD1

The compiler creates a post-compiled module file mod1.mod in the current directory. An object file is also created for the module.

Compiling a source file that contains multiple module declarations will create multiple module files, but only a single object file. If you need a separate object file for each module, place only one module declaration in each file.

If a source file does not contain the main program and you only need to create module files, specify the -c option to prevent linking.

An object file is not needed if there are only INTERFACE or constant (PARAMETER) declarations. It is needed for all other types of declarations including variables.

2.1.3.2 Using Module Files

Once they are created, you can copy module files into an appropriate shared or private directory. You reference a module file specifying the name in a USE statement (use association). For example:

USE MOD1

When selecting a directory location for a set of module files, consider how your application will be built, including:

• Whether the module files need to be available privately, perhaps for testing purposes (not shared).
• Whether you want the module files to be available to other users on your project or available system-wide (shared).
• Whether test builds and final production builds will use the same directory or different ones.

To locate module files specified in USE statements, the Compaq Fortran compiler searches the following directories:

• The current working directory
• Each directory specified by one or more -idir options on the command line.

Suppose you need to compile a main program proj_main that contains one or more USE statements. To request that the compiler look for module files in the additional directories /usr/proj_module/f90 and then /usr/common/f90 (after looking in the current directory), enter the following command line:

% f90 proj_main.f90 -I/usr/proj_module/f90 -I/usr/common/f90

If you specify multiple directories, the order of -idir options on the f90 command line determines the directory search order.

You cannot specify a .mod file directly on the f90 command line.

Module nesting depth is unlimited. If you will use many modules in a program, check the process and system descriptor limit (see Section 1.1).

For More Information:

• On specific f90 command-line options, including -idir , see Chapter 3.
• On an example program that uses a module, see Section 1.3.

You can create include files with a text editor. If needed, you can copy include files to a shared or private directory.

When selecting a directory location for a set of include files or text libraries, consider how your application is to be built, including:

• Whether the include files need to be available privately, perhaps for testing purposes (not shared).
• Whether you want the files to be available to other users on your project or available system-wide (shared).
• Whether test builds and final production builds will use the same directory or a different one.

Include file names can have any suffix. Use an INCLUDE statement to request that the specified file containing source lines be included by the compiler in place of the INCLUDE statement.

The INCLUDE statement has the following form:

INCLUDE 'name' INCLUDE 'name.typ'

You can also include a file with a pathname specified with the following form:

INCLUDE '/pathname/name' INCLUDE '/pathname/name.typ'

If you specify the -vms option, you can specify /LIST or /NOLIST after the file name. For example:

INCLUDE '/pathname/name/LIST' INCLUDE 'name.f90/NOLIST'

You can also specify the -show include option to request that source lines from included files appear in the listing file (see Section 3.82).

When the INCLUDE Statement Specifies a Pathname

Specifying pathname limits the directory searching done for the named file. For example, pathname might specify a directory /usr/users/proj for the file named common_proj.f90 :

INCLUDE 'usr/users/proj/common_proj.f90'

If a directory pathname is specified, only the specified directory is searched.

When the INCLUDE Statement Omits a Pathname

When the INCLUDE statement omits a pathname, one or more directories are searched for the specified file name.

To locate include files specified in INCLUDE statements without a pathname, the Compaq Fortran compiler searches directories in the following order:

1. The directory that the source file resides in ( -vms option was omitted) or the current process default directory ( -vms option was specified)
2. Each directory specified by one or more -idir options.
3. The /usr/include directory (unless the -noinclude option was specified)

Compaq Fortran allows you to use multiple methods to specify which directories are searched for include files:

• You can specify one or more additional directories for the compiler to search by using one or more -idir options.
• You can request that the standard directory /usr/include not be searched by specifying the -noinclude option.
• Depending on whether the -vms option was specified, the Compaq Fortran compiler searches either in the current process default directory or in the directory containing the source file that references the include file.

The output produced by the f90 command includes:

• An object file (such as test.o ), if you specify the -c option on the command line
• An executable file (such as a.out ), if you omit the -c option
• A listing file (such as test.l ), if you specify the -v option
• One or more module files (such as datadef.mod ), if the source file contains one or more MODULE statements

You control the production of these files by specifying the appropriate options on the f90 command line. Unless you specify the -c option, the compiler generates a single temporary object file (see Section 2.1.5.2), whether you specify one source file or multiple source files separated by blanks. The ld linker is then invoked to link the object file into one executable program file.

If fatal errors are encountered during compilation, or if you specify certain options such as -c , linking does not occur.

2.1.5.1 Naming Output Files

To specify a file name for the executable program file (other than a.out ), use the -o output option, where output specifies the file name. The following command requests a file name of prog1.out for the source file test1.f :

% f90 -o prog1.out test1.f

If you specify the -c option with the -o output option, you rename the object file (not the executable program file). If you specify -c and omit the -o output option, the compiler names the object file using the first specified file name (with a .o suffix substituted for the source file suffix).

You can also use the mv command to rename a file.

2.1.5.2 Temporary Files

Temporary files created by the compiler or a preprocessor reside in the /tmp directory. For example, when an f90 command requests that the compiler create an object file and pass it to the linker, the file is created in, and later deleted from, the /tmp directory (unless you specified the -k option).

You can set the environment variable TMPDIR to specify a directory to contain temporary files if /tmp is not acceptable. For performance reasons, use a local disk (rather than a NFS mounted disk) to contain the temporary files.

For information about the commands used to set and unset environment variables, see Appendix B.

To view the file name and directory where each temporary file is created, use the -v option. To create (and retain) object files in your current working directory, use the -c option. Any object files ( .o files) that you specify on the f90 command line are retained.

The TMPDIR environment variable is also used during program execution (run-time) to specify which directory to contain any scratch files your program creates.

2.1.6 Using Multiple Input Files: Effect on Output Files

When you specify multiple source files, the following options control the production of output files and also influence whether Compaq Fortran can apply certain levels of optimizations:

• The -c option prevents linking. This option also creates and retains the object file in the current working directory.
• The -k option keeps temporary files.
• The -o output option names the output file.

A description of the interaction of these options follows:

• If you omit both the -c and the -k options, the specified Fortran 95/90 source files are compiled together into a single object file and then linked.
  Since all the Fortran 95/90 source files are compiled together into a single object file, full interprocedure optimizations can occur. Any temporary object files created by the compiler are deleted by the linker after it creates the executable program. The default optimization level is -o4 (unless you specify -g2 or -g ).
• If you specify the -c option and you want to allow full interprocedure optimizations to occur, you should also specify the -o output option.
  The combination of the -c and -o output options creates a single object file ( output ) from multiple Fortran 95/90 source files, allowing full interprocedure optimizations. The object file can be linked later.
  For example, the following command uses both the -c and -o output options to allow interprocedure optimization (explicitly requested by -o4 ):

  % f90 -c -o out.o -O4 ax.f bx.f cx.f

• If you specify the -c option without specifying the -o output option, or if you specify the -k option, each source file is compiled into an object file, creating one object file for each input source file specified. This is acceptable if you specified no optimization ( -o0 ) or local optimization ( -o1 ).
  An information message appears when you specify multiple input files and specify an option that creates multiple object files (such as -c without -o output ) and specify or imply global optimization ( -o2 , -o3 , -o4 , or -o5 ).
• If you specify the -c option, you must link the object file(s) later by using a separate f90 command. This allows incremental compilation of a large application, perhaps by means of a makefile processed by the make command.
  However, keep in mind that either omitting the -c option or using the -c option in combination with the -o output option provides the benefit of full interprocedure optimizations for compiling multiple Fortran source files.

When you request a listing file ( -v option), a single listing file is created unless you specify the -c option. If you specify the -c option and the -v option, separate listing files are created.

2.1.7 Examples of the f90 and fort Commands

The following examples show the use of the f90 command. On Linux systems, use the fort command instead of the f90 command.

2.1.7.1 Compiling and Linking Multiple Files

The following f90 command compiles the Compaq Fortran free format source files ( aaa.f90 , bbb.f90 , ccc.f90 ) into a single temporary object file:

% f90 -V aaa.f90 bbb.f90 ccc.f90

This f90 command invokes the ld linker and passes the temporary object file to ld , which it uses to produce the executable file a.out . The Compaq Fortran compiler ( -v option) creates the listing file aaa.l .

The following f90 command compiles all Compaq Fortran fixed-format (or tab-format) source files with file names that end with .f into a temporary object file:

% f90 -V *.f

The ld linker produces the a.out file. The listing file (produced when the -v option is specified) assumes the name of the first file, aaa.l .

2.1.7.2 Retaining an Object File and Preventing Linking

The following f90 command compiles, but does not link, the free-format source file typedefs_1.f90 , which contains a MODULE TYPEDEFS_1 statement:

% f90 -c typedefs_1.f90

This command creates files typedefs_1.mod and typedefs_1.o . Specifying the -c option retains the object file typedefs_1.o and prevents linking.

2.1.7.3 Compiling Fortran 95/90 and C Source Files and Linking an Object File

The following f90 command compiles the free-format Compaq Fortran main program ( myprog.f90 ). The main program calls a function written in C and references the module TYPEDEFS_1 with a USE TYPEDEFS_1 statement (uses the object file created in the previous example). The C routine named utilityx_ is declared in a file named utilityx.c . All sources files are compiled and the object files are passed to the linker:

% f90 myprog.f90 typedefs_1.o utilityx.c

This command does the following:

1. Compiles myprog.f90 with the Compaq Fortran compiler. The module file typedefs_1.mod is read from the current directory.
2. The C compiler compiles utilityx.c .
3. The ld linker links all three object files together into the executable program named a.out .

The following f90 command compiles the free-format Compaq Fortran source files circle-calc.f90 and sub.f90 together, producing one object file named circle.o :

% f90 -c -o circle.o circle-calc.f90 sub.f90

The default optimization level ( -o4 ) applies to both source files during compilation and uses the default loop unrolling. Because the -c option is specified, the object file is not passed to the ld linker and is not deleted. In this case, the named output file is the object file.

Like the previous command, the following f90 command compiles multiple source files:

% f90 -o circle.out circle-calc.f90 sub.f90

Because the -c option was omitted, an executable program named circle.out is created.

2.1.7.5 Specifying an Additional Linker Library

The following f90 command compiles a free-format source file myprog.f90 using default optimization, and passes an additional library for the linker to search:

% f90 typedefs_1.o myprog.f90 -lcxml

The file is processed at optimization level -o4 and then linked with the object file typedefs_1.o . The -lcxml option instructs the linker to search in the libcxml library for unresolved references (in addition to the standard list of libraries the f90 command passes to the linker).

2.1.7.6 Requesting Additional Optimizations

The following f90 command compiles the free-format Compaq Fortran source files circle-calc.f90 and sub.f90 together using software pipelining optimizations ( -o5 ):

% f90 -O5 -unroll 3 circle-calc.f90 sub.f90

The loops within the program are unrolled 3 times ( -unroll 3 ). Loop unrolling occurs at optimization level -o3 or above.

2.1.8 Using Listing Files

If you expect your program to have compilation errors, you should request a separate listing file ( -v option).

For example, the following command compiles Compaq Fortran source files with file names that end with .f , and ld creates an executable file named a.out :

% f90 -V *.f

The listing file assumes the name of the first file. If the first file was named aaa.f , the listing file is named aaa.l .

Using a listing file provides such information as the column pointer (1) that indicates the exact part of the line that caused the error (see Section 2.3.2). Especially for large files, consider obtaining a printed copy of the listing file you can reference while editing the source file.

For More Information:

• On calling programs written in other languages, see Chapter 11.
• On options for the f90 command, see Chapter 3.
• On f90 command-line options and their categories, see Table 3-1.

The f90 and fort driver programs control which software components operate on the files and options specified on the command line and their order of use. See Figure 2-1.

Figure 2-1 Driver Programs and Software Components

On Tru64 UNIX Alpha systems, the f90 driver program passes options and files not intended for the Compaq Fortran compiler to the cc driver program.

On Linux Alpha systems, the fort driver program passes options and files not intended for the Compaq Fortran compiler to the cc driver program. On Linux systems, this is a symbolic link to, generally, gcc or ccc .

The f90 (or fort ) driver program does the following:

1. Examines file name suffix information and groups files and options specified on the command line.
2. Runs the requested preprocessors (if any) on any Fortran files.
3. Runs the Compaq Fortran compiler to process Fortran files.
4. Passes grouped input files, processed source files, and grouped options to the cc driver program in the following order:
   1. All options, except for any -lstring options, are passed.
   2. All object files are grouped and passed.
   3. All non-Fortran source files (such as a C program with a .c suffix) are grouped and passed.
   4. All archive libraries ( .a suffix) are grouped in the same order specified on the f90 command line and passed.
   5. All shared libraries ( .so suffix) are grouped in the same order specified on the f90 command line and passed.
   6. All user-specified -lstring options are grouped in the same order specified on the f90 command line and passed.
   7. All -lstring options automatically added by the f90 command are grouped with other information and passed.

The cc driver program then does the following:

1. Runs cpp if necessary.
2. Runs the C compiler cc if necessary.
3. Passes library-related information to and runs the ld linker.

Upon return to the command line, the f90 or fort driver program returns one of the following status values:

• 0 (zero)---success
• 1---failure
• 2---subprocess failure (preprocessor, the decfort90 compiler, cc , or ld )
• 3---signal

Because the f90 or fort driver program runs other software components such as the C compiler, error messages may be returned by these other components. For instance, ld may return a message if it cannot resolve a global reference. Using the -v option on the f90 command line can help clarify which component is generating the error.

2.2.1 make Facility

The make facility is often used to automate building large programs. See make(1).

2.2.2 Options Passed to the cc Driver or ld Linker

Certain options are passed directly from the f90 or fort driver program to the cc driver program. These options do not generally apply to compiling Compaq Fortran source files, but might be used to:

• Process C language source files or intermediate files using the f90 or fort command instead of the cc or ccc command
• Pass information to ld .

With the -w c[c...],arg1[,arg2]... option, you can pass ld options not otherwise provided by the f90 command directly to ld .

When compiling a program that contains both Compaq Fortran and C language source files, you can usually compile with a single f90 command. Any options that f90 does not recognize are passed to cc , such as the following:

• Compilation environment options, such as -systype name and -yenvironment
• Preprocessor ( cpp ) options, such as -m
• C language compatibility option, such as -migrate
• Memory location (performance) options, such as -d num , -t num , and -taso
• Other options listed in cc(1)

Certain options recognized and used by f90 also apply to cc , such as the -on option. If needed, you can compile the C files using the cc command (instead of the f90 command) with the -c option, and then compile the Compaq Fortran files and the (C language) object files using the f90 command.

For more information on the options processed by cc and ccc , see cc(1) and ccc(1) (for most options) or ld(1).

2.3 Compiler Limits, Diagnostic Messages, and Error Conditions

The following sections discuss the compiler limits and error messages from the compiler and linker. Other components can report messages, as described in Section 2.2.

2.3.1 Compiler Limits

Table 2-3 lists the limits to the size and complexity of a single Compaq Fortran program unit and to individual statements contained within it.

Table 2-3 Compiler Limits

Language Element	Limit
Actual number of arguments per CALL or function reference	Limited only by memory constraints.
Arguments in a function reference in a specification expression	255
Array dimensions	7
Array construction nesting	20
Array elements per dimension	9,223,372,036,854,775,807 1 = 2**63-1
Constants; character and Hollerith	7198 characters
Constants; characters read in list-directed I/O	2048 characters
Continuation lines	511
Data and I/O implied DO nesting	7
DO and block IF statement nesting (combined)	128
DO loop index variable	9,223,372,036,854,775,807 1 = 2**63-1
Format group nesting	8
Format statement length	2048 characters
Fortran source line length	fixed form: 72 (or 132 if -extend_source is in effect) characters free form: 7200 characters
INCLUDE file nesting	20 levels
Labels in computed or assigned GOTO list	Limited only by memory constraints.
Lexical tokens per statement	20000
Named common blocks	Limited only by memory constraints.
Parentheses nesting in expressions	Limited only by memory constraints.
Structure nesting	30
Symbolic-name length	63 characters

The following are usually limited by the amount of process virtual address space available, as determined by system parameters:

• Amount of data storage
• Size of arrays
• Total size of executable programs

For information on increasing your limits, see Section 1.1.

2.3.2 Compiler Diagnostic Messages and Error Conditions

The Compaq Fortran compiler identifies syntax errors and violations of language rules in the source program. If the compiler finds any such errors, it writes messages to the stderr output file and any listing file. If you enter the f90 command interactively, the messages are displayed on your terminal.

Compiler messages have the following format:

f90: severity: filename, line n, message-text [text-in-error] --------^

The pointer ( ---^ ) indicates the exact place on the source program line where the error was found. For example, the following error message shows the format and message text in a listing file when an END DO statement was omitted:

f90: Severe: echar.f, line 7: Unclosed DO loop or IF block DO I=1,5 --------^

Diagnostic messages usually provide enough information for you to determine the cause of an error and correct it.

2.3.3 Linker Diagnostic Messages and Error Conditions

If the linker detects any errors while linking object files, it displays messages about their cause and severity. If any errors occur, the linker does not produce an executable program file.

Linker messages are descriptive, and you do not normally need additional information to determine the specific error.

On Tru64 UNIX systems, the general format for ld messages is:

ld: message-text

On Linux systems, the general format for ld messages is:

message-text

The message-text can be on multiple lines and is sometimes accompanied by an f90 or fort error.

Some common errors that occur during linking resemble the following:

• "An object file has compilation errors."
  This error occurs when you attempt to link a file that had warnings or errors during compilation. Although you can usually link compiled files for which the compiler generated messages, you should verify that the files will actually produce the output you expect.
• "The files being linked define more than one transfer address."
  The linker generates a warning if more than one main program has been defined. For example, this can occur when an extra END statement exists in the program. The executable program file created by the linker in this case can be run; the entry point to which control is transferred is the first one that the linker found.
• "A reference to a symbol name remains unresolved" or "undefined reference."
  This error occurs when you omit required file or library names from the f90 or ld command and the linker cannot locate the definition for a specified global symbol reference. Use the -y option to the ld command to determine which files refer to each missing symbol. See ld(1) for more information.

If an error occurs when you link files, you may be able to correct it by retyping the command string and specifying the correct routines or libraries ( -lstring option, -ldir option), or by specifying the object library or object files on the command line.

For More Information:

• On specifying object library or object files on the command line and related information on linking, see Section 2.5.
• On linker messages, see your operating system documentation.
• On run-time messages, see Chapter 8.

In addition to options on the command line, several statements used in the body of a Fortran program and cpp directives also influence the compilation process.

• The INCLUDE statement incorporates external source code into your programs during the compilation process.
  If you omit the directory path from the file specification in the INCLUDE statement, the directory searched depends on whether the -vms option was specified or omitted. For more information, see Section 2.1.4.
• The USE statement incorporates a post-compiled module file into your programs during the compilation process. For more information, see Section 2.1.3.
• The OPTIONS statement sets compiler options that would otherwise be specified on the f90 command. The options specified on an OPTIONS statement take precedence over options specified on the f90 command line if a conflict occurs. Each OPTIONS statement applies only to the program unit in which it appears.
• You can use the general cDEC$ directives to perform tasks during compilation. You can specify the following, for example:
  • The identification field in the object file
  • An alternate name (alias) for external objects, such as subprograms
  • Alternate ways of passing arguments and naming for external objects
  • Common block attributes
  • The -align attributes for record structures and common blocks
  • The title and subtitle for listings
  • Properties for data objects and procedures
  
  cDEC$ directives take precedence over the f90 command-line options.
• A # character in column 1 indicates a cpp directive when processing if the -cpp option is specified. You can specify that only preprocessing (no compilation) occurs by specifying the -p option, perhaps for debugging purposes.

For More Information:

• On Compaq Fortran statements, including INCLUDE, OPTIONS, and USE, see the Compaq Fortran Language Reference Manual.
• On cDEC$ directives related to passing arguments and external names, see Section 11.2.
• On cpp and its directives, see cpp(1).

Within a Fortran 95/90 program, references to procedures defined outside your program unit need to be declared as external symbols by using the EXTERNAL statement. (In order for BLOCK DATA statement symbols to be resolved by the linker, the BLOCK DATA symbol must be declared EXTERNAL and not have its data type declared in the source program unit.)

During compilation of multiple source files that will be placed into a single object or executable file, the Compaq Fortran compiler resolves those symbols referenced in one compilation unit and defined in another before linking occurs.

Upon successful compilation of a Compaq Fortran program, the f90 command specifies certain libraries for ld to search for unresolved external symbols in the object file (or files), such as calls to routines in libraries.

Table 2-4 shows the standard f90 library file names that are searched by ld .

Table 2-4 Libraries Automatically Searched When Using the f90 Command

File Name	-lstring Option Form
libufor	-lufor
libfor	-lfor
libfutil	-lfutil
(TU*X ONLY) libshpf or libphpf (see text)	-lshpf , -lphpf , or -lphpfp (see text)
libm	-lm
libots	-lots
libc	-lc

(TU*X ONLY) If you specify -omp or -mp (requests directed parallel processing), the libots3 library is searched.

Which High Performance Fortran (HPF) library is searched (TU*X ONLY) depends on which command-line option is specified:

• If you specify -hpf , libphpf is searched.
• If you omit -hpf , libshpf is searched.

The Compaq Fortran kit provides both shared and archive libraries. For a complete list of Compaq Fortran Run-Time Library files, see f90(1).

2.5.1 Specifying Additional Object Libraries

You can also specify additional object libraries on the command line by using certain options or by providing the file name of the library. These object libraries are also searched by ld for unresolved external references.

When f90 specifies certain libraries to ld , it provides a standard list of f90 library file names to ld . The ld linker tries to locate each of these library file names in a standard list of library directories; ld attempts to locate each object library file name first in one directory, then in the second, and then in the third directory on its search list of directories.

To display a list of the compilers invoked, files processed, and libraries accessed during linking, specify the -v option on the f90 command line.

In addition to an object file created by the compiler, any linker options and object files specified on the f90 command are also passed to the ld linker. The linker loads object files according to the order in which they are specified on the command line. Because of this, you must specify object libraries after all source and object files on the f90 command line.

For more details on the interaction of the f90 command with other components, see Section 2.2.

To help you identify undefined references to routines or other symbols in an object file, consider using the nm command. For instance, the following nm command filtered by the grep command lists all undefined (U) symbols:

% nm -o ex.o | grep U

If the symbol is undefined, a "U" appears in the column before the symbol name. Any symbols with a U in their names are also displayed by this use of grep .

You can control the libraries to be searched with these methods:

• To specify additional object library file names for ld to search, use the -lstring option at the end of the f90 command line. Each occurrence of the -lstring option specifies an additional file name that is added to the list of object libraries for ld to locate.
• In addition to the standard directories in which ld tries to locate the library file names, you can use the -ldir option to specify another directory.
  Unlike the -lstring option that adds an object library file name for ld to search, the -ldir option adds an additional directory in which ld will look for library file names.
  The standard ld directories are searched after the directories specified by the -ldir option.
  The following example specifies the additional object library path /usr/lib/mytest :

  % f90 simtest.f -L/usr/lib/mytest

  
  For a list of the standard ld directories searched, see Section 3.58.

• You can specify the pathname and file name of an object library as you would specify any file. Specifying each object library that resides in special directories in this manner is an alternative to specifying the library by using the -lstring or -ldir option. Specifying the pathname and file name of an object library can reduce the amount of searching the linker must do to locate all the needed object files.
  For instance, instead of specifying the options -l/usr/jones and -lfft , this example specifies the directory path and file name of the library file:

  % f90 main.o more.o rest.o /usr/jones/libfft.a

  
  In certain cases, you may need to specify the pathname and file name instead of using the -lstring or -ldir options for the linker to resolve global symbols with shared libraries.

• You can indicate that ld should not search its list of standard directories at all by specifying the -l option. When you do so, you must specify all libraries on the f90 command line in some form, including the directory for f90 standard libraries.
  To specify all libraries, you might use the -l option in combination with the -ldir option on the same f90 command line.

External references found in an archive library result in the referenced routine being included in the resulting executable program file at link time.

External references found in a shared object library result in a special link to that library being included in the resulting executable program file, instead of the actual routine itself. When you run the program, this link gets resolved by either using the shared library in memory (if it already exists) or loading it into memory from disk.

Certain f90 options influence whether ld searches for an archive ( .a ) or shared object ( .so ) library on the standard list of f90 libraries, as well as any additional libraries specified by using the -lstring or -ldir options:

• The -call_shared option is the default. It indicates that .so files are searched before .a files. As ld attempts to resolve external symbols, it looks at the shared library before the corresponding archive library. For instance, /usr/shlib/libc.so is searched before /usr/lib/libc.a .
  References to symbols found in .so libraries are dynamically loaded into memory at run time.
  References to symbols found in .a libraries are loaded into the executable program file at link time.
• The -non_shared option indicates that only .a files are searched, so the object file created contains static references to external routines. These static references are loaded into the executable program at link time, not at run time. Corresponding .so files are not searched.
  The following example requests that the standard f90 .a files be searched instead of the corresponding .so files:

  % f90 -non_shared main.f rest.o

• The -shared option requests the creation of an executable program to be included in a shared library.
  If you specify the -c option to inhibit linking, an object file ( .o file) is created that can subsequently be processed by ld to create a shared library.
  If you omit the -c option, the f90 command creates a shared library ( .so file).
  In either case, use the -o option to name the resulting object file or shared library with the correct file name and suffix.
  For more information about creating a shared library using either the f90 command or the ld command, see Section 2.6, Creating Shared Libraries.

When you link your program with a shared library, all symbols must be referenced before ld searches the shared library. You should always specify libraries at the end of the f90 command line, after all file names. Unless you specify the -non_shared option, shared libraries will be searched before the corresponding archive libraries.

For instance, the following command generates an error if the file rest.o references routines in the library libx :

% f90 -call_shared test.f -lX rest.o

The correct command specifies the library at the end of the line, as follows:

% f90 -call_shared test.f rest.o -lX

Link errors can occur with symbols that are defined twice, as when both an archive and a shared object library are specified on the same command line. In general, specify any archive libraries after the last file name, followed by any shared libraries at the end of the command line.

Before you reference a shared library at run time, it must be installed. See Section 2.6, Creating Shared Libraries.

2.6 Creating Shared Libraries

To create a shared library from a Fortran source file, process the files using the f90 command:

• You must specify the -shared option to create the .so file.
• You can specify the -o output option to name the output file.
• If you omit the -c option, you will create a shared library ( .so file) directly from the f90 command line in a single step.
  If you also omit the -o output option, the file name of the first Fortran file on the command line is used to create the file name of the .so file. You can specify additional options associated with shared library creation.
• If you specify the -c option, you will create an object file ( .o file) that you can name with the -o option. To create a shared library, process the .o file with ld , specifying certain options associated with shared library creation.

You can specify multiple source and object files when creating a shared library by using the f90 command.

2.6.1 Creating a Shared Library with a Single f90 Command

You can create a shared library ( .so ) file with a single f90 command:

% f90 -shared octagon.f90

The -shared option is required to create a shared library. The name of the source file is octagon.f90 . You can specify multiple source files and object files.

The -o option was omitted, so the name of the shared library file is octagon.so .

2.6.2 Creating a Shared Library with f90 and ld Commands

You first must create the .o file, such as octagon.o in the following example:

% f90 -O3 -c octagon.f90

The file octagon.o is then used as input to the ld command to create the shared library named octagon.so :

% ld -shared -no_archive octagon.o \ -lUfor -lfor -lFutil -lm -lots -lc

Note that the -no_archive option is available only on Tru64 UNIX systems.

• The -shared option is required to create a shared library.
• The -no_archive option (TU*X ONLY) indicates that ld should not search archive libraries to resolve external names (only shared libraries).
• The name of the object file is octagon.o . You can specify multiple object ( .o ) files.
• The -lufor and subsequent options are the standard list of libraries that the f90 command would have otherwise passed to ld . When you create a shared library, all symbols must be resolved. For more information about the standard list of libraries used by Compaq Fortran, see Section 2.5.

Consider the following when deciding whether to use a single f90 command ( -c omitted) or both the f90 ( -c present) and ld commands to create a shared library:

• Certain ld options may not be available from the f90 command line. If you need to use those options, use the two-command method (specify f90 -c and subsequently use ld ). Such options include -check_registry and -update_registry (see ld(1)) that are available only on Tru64 UNIX systems.
• If you use a single f90 command with -shared and omit -c , you do not need to specify the standard list of f90 libraries by using the -lstring option.

In addition to the options shown in Section 2.6.1 and Section 2.6.2, certain other ld options may be needed. For instance, to optimize shared library startup, use the -update_registry and -check_registry options (TU*X ONLY), which preassign a starting address in virtual memory to a shared library using the file /usr/shlib/so_locations .

For More Information:

• On the relevant ld options, see the ld(1) reference page.
• On the standard list of libraries used by Compaq Fortran, see Section 2.5.

When creating a shared library with ld , be aware of the following restrictions:

• Shared libraries must not be linked with archive libraries.
  When creating a shared library, you can only depend on other shared libraries for resolving external references. If you need to reference a routine that currently resides in an archive library, either put that routine in a separate shared library or include it in the shared library being created. You can specify multiple object ( .o ) files when creating a shared library.
  To put a routine in a separate shared library, obtain the source or object file for that routine, recompile if necessary, and create a separate shared library. You can specify an object file when recompiling with the f90 command or when creating the shared library with the ld command.
  To include a routine in the shared library being created, put the routine (source or object file) with other source files that make up the shared library and recompile if necessary.
  Then create the shared library, making sure that you specify the file containing that routine either during recompilation or when creating the shared library. You can specify an object file when recompiling with the f90 command or when creating the shared library with the ld command.
• When creating shared libraries, all symbols must be defined (resolved).
  Because all symbols must be defined to ld when you create a shared library, you must specify the shared libraries on the ld command line, including all standard Compaq Fortran libraries. The list of standard Compaq Fortran libraries might be specified by using the -lstring option, as in the previous example in this section.

For other restrictions imposed by the operating system, see the Compaq Tru64 UNIX Programmer's Guide.

2.6.5 Installing Shared Libraries (TU*X ONLY)

Once the shared library is created, it must be installed for private or system-wide use before you run a program that refers to it:

• To install a private shared library (when you are testing, for example), set the environment variable LD_LIBRARY_PATH, as described in loader(5).
• To install a system-wide shared library, place the shared library file in one of the standard directory paths used by ld (see loader(5) or Section 3.58).

For complete information on installing shared libraries, see the Compaq Tru64 UNIX Programmer's Guide.