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 follows:

ld: message-text

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

message-text

The message-text may 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 ( -l string option, -L dir 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 option arguments on the f90 command, 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.5.
• The USE statement incorporates a post-compiled module file into your programs during the compilation process. For more information, see Section 2.1.4.
• 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 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.
• 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.

You can also specify additional object libraries on the f90 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.1.

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 .

2.5.1 Specifying Additional Object Libraries

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

• To specify additional object library file names for ld to search, use the -l string option at the end of the f90 command line. Each occurrence of the -l string option specifies an additional file name that is added to the list of object libraries for ld to locate.
  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 , libphpf , or libphpfp (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 f90 options are specified:

  • If you specify -pprof and specify -wsf (or -wsf 2 or greater), libphpfp is searched.
  • If you omit -pprof and specify -wsf (or -wsf 2 or greater), libphpf is searched.
  • If you omit -wsf or specify -wsf 1 , 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).
• In addition to the standard directories in which ld tries to locate the library file names, you can use the -L dir option to specify another directory.
  Unlike the -l string option that adds an object library file name for ld to search, the -L dir 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 -L dir 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.51.

• 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 -l string or -L dir 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 -l string or -L dir 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 -L dir 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 -l string or -L dir 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.

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. For further information on creating or installing a shared library, see Section 2.6.

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 additional information on the relevant ld options, see the ld(1) reference page.

For more information about 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.