# Compaq Fortran
User Manual for
Tru64 UNIX and
Linux Alpha Systems

Previous | Contents | Index

# Chapter 2
Compiling and Linking Compaq Fortran Programs

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

Note To invoke the Compaq Fortran compiler, use: `f90` on Tru64 UNIX Alpha systems `fort` command on Linux Alpha systems This chapter uses `f90` to indicate invoking Compaq Fortran on both systems, so replace this command with `fort` if you are working on a Linux Alpha system. To invoke the Compaq C compiler, use: `cc` on Tru64 UNIX Alpha systems `ccc` on Linux Alpha systems This chapter uses `cc` to indicate invoking Compaq C on both systems, so replace this command with `ccc` if you are working on a Linux Alpha system.

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.

## 2.1.3 Creating and Using Module Files

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.

## 2.1.4 INCLUDE Statement and Using Include Files

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.

## 2.1.5 Output Files: Executable, Object, and Temporary

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` .

### 2.1.7.4 Renaming the Output File

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.

# 2.2 Driver Programs and Passing Options to cc and ld

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

1Also check available process and system virtual memory; see Section 1.1.

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.

# 2.4 Compilation Control: Statements and Directives

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)`.

# 2.5 Linking Object Libraries

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.

## 2.5.2 Specifying Types of Object Libraries

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.

## 2.5.3 Specifying Shared Object 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.

## 2.6.3 Choosing How to Create a Shared Library

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.

## 2.6.4 Shared Library Restrictions

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.

Previous | Next | Contents | Index