Fortran Programming Guide | ![]() ![]() ![]() ![]() ![]() |
Libraries
This chapter describes how to use and create libraries of subprograms. Both static and dynamic libraries are discussed.
Understanding Libraries
A software library is usually a set of subprograms that have been previously compiled and organized into a single binary library file. Each member of the set is called a library element or module. The linker searches the library files, loading object modules referenced by the user program while building the executable binary program. See
ld
(1) and the Solaris Linker and Libraries Guide for details.There are two basic kinds of software libraries:
- Static library. A library in which modules are bound into the executable file before execution. Static libraries are commonly named
lib
name.a
. The.a
suffix refers to archive.- Dynamic library. A library in which modules can be bound into the executable program at runtime. Dynamic libraries are commonly named
lib
name.so
. The.so
suffix refers to shared object.Typical system libraries that have both static (
.a
) and dynamic (.so
) versions are:
- Fortran 77 libraries:
libF77
,libM77
- Fortran 95 libraries:
libfsu
,libfui
,libfai
,libfai2
,libfsunai
,libfprodai
,libfminlai
,libfmaxlai
,libminvai
,libmaxvai
,libf77compat
- VMS Fortran libraries:
libV77
- C libraries:
libc
There are two advantages to the use of libraries:
- There is no need to have source code for the library routines that a program calls.
- Only the needed modules are loaded.
Library files provide an easy way for programs to share commonly used subroutines. You need only name the library when linking the program, and those library modules that resolve references in the program are linked and merged into the executable file.
Specifying Linker Debugging Options
Summary information about library usage and loading can be obtained by passing additional options to the linker through the
LD_OPTIONS
environment variable. The compiler calls the linker with these options (and others it requires) when generating object binary files.Using the compiler to call the linker is always recommended over calling the linker directly because many compiler options require specific linker options or library references, and linking without these could produce unpredictable results.
Example: Using
demo%setenv LD_OPTIONS '-m -Dfiles'
demo%f77 -o myprog myprog.f
LD_OPTIONS
to create a load map:Some linker options do have compiler command-line equivalents that can appear directly on the
f77
orf95
command. These include-B
x, -d
x, -G, -h
name,
path
-R,
and-ztext.
See thef77
(1) andf95
(1) man pages or the Fortran User's Guide for details.More detailed examples and explanations of linker options and environment variables can be found in the Solaris Linker and Libraries Guide.
Generating a Load Map
The linker
-m
option generates a load map that displays library linking information. The routines linked during the building of the executable binary program are listed together with the libraries that they come from.Example: Using
-m
to generate a load map:
Listing Other Information
Additional linker debugging features are available through the linker's
-D
keyword option. A complete list can be displayed using-Dhelp
.Example: List linker debugging aid options using the
-Dhelp
option:
For example, the
-Dfiles
linker option lists all the files and libraries referenced during the link process:
See the Linker and Libraries Guide for further information on these linker options.
Consistent Compiling and Linking
Ensuring a consistent choice of compiling and linking options is critical whenever compilation and linking are done in separate steps. Compiling any part of a program with any of the following options requires linking with the same options:
-a
,-autopar
,-B
x,-fast
,-G
,-L
path,-l
name,-mt
,-xmemalign
,-nolib
,-norunpath
,-p
,-pg
,-xlibmopt
,-xlic_lib=
name,-xprofile=
pExample: Compiling
sbr.f
with-a
andsmain.f
without it, then linking in separate steps (-a
invokestcov
old style profiling):
demo%f77 -c -a sbr.f
demo%f77 -c smain.f
demo%f77 -a sbr.o smain.o
{link step; pass -a to the linker}Also, a number of options require that all source files be compiled with that option. These include:
-aligncommon
,-autopar
,-d
x,-dalign
,-dbl
,-explicitpar
,-f
,-misalign
,-native
,-parallel
,-pentium
,-xarch=
a,-xcache=
c,-xchip=
c,-xF
,-xtarget=
t,-ztext
See the
f77
(1) andf95
(1) man pages and the Fortran User's Guide for details on all compiler options.Setting Library Search Paths and Order
The linker searches for libraries at several locations and in a certain prescribed order. Some of these locations are standard paths, while others depend on the compiler options
-R
path,-l
library, and-L
dir and the environment variableLD_LIBRARY_PATH
.Search Order for Standard Library Paths
The standard library search paths used by the linker are determined by the installation path, and they differ for static and dynamic loading. <install-point> is the path to where the Fortran compilers have been installed. In a standard install of the software this is
/opt
.Static Linking
While building the executable file, the static linker searches for any libraries in the following paths (among others), in the specified order:
<install-point>/SUNWspro/lib
Sun shared libraries /usr/ccs/lib/
Standard location for SVr4 software /usr/lib
Standard location for UNIX software
These are the default paths used by the linker.
Dynamic Linking
The dynamic linker searches for shared libraries at runtime, in the specified order:
- Paths specified by user with
-R
path- <install-point>
/SUNWspro/lib/
/usr/lib
standard UNIX defaultThe search paths are built into the executable.
LD_LIBRARY_PATH
Environment VariableUse the
LD_LIBRARY_PATH
environment variable to specify directory paths that the linker should search for libraries specified with the-l
library option.Multiple directories can be specified, separated by a colon. Typically, the
LD_LIBRARY_PATH
variable contains two lists of colon-separated directories separated by a semicolon:The directories in dirlist1 are searched first, followed by any explicit
-L
dir directories specified on the command line, followed by dirlist2 and the standard directories.That is, if the compiler is called with any number of occurrences of
-L
, as in:
f77
...-L
path1 ...-L
pathn...
dirlist1 path1 ... pathn dirlist2 standard_paths
When the
LD_LIBRARY_PATH
variable contains only one colon-separated list of directories, it is interpreted as dirlist2.In the Solaris operating environment, a similar environment variable,
LD_LIBRARY_PATH_64
can be used to overrideLD_LIBRARY_PATH
when searching for 64-bit dependencies. See the Solaris Linker and Libraries Guide and the ld(1) man page for details.
- On a 32-bit SPARC processor,
LD_LIBRARY_PATH_64
is ignored.- If only
LD_LIBRARY_PATH
is defined, it is used for both 32-bit and 64-bit linking.- If both
LD_LIBRARY_PATH
andLD_LIBRARY_PATH_64
are defined, 32-bit linking will be done usingLD_LIBRARY_PATH
, and 64-bit linking withLD_LIBRARY_PATH_64
.
Note Use of theLD_LIBRARY_PATH
environment variable with production software is strongly discouraged. Although useful as a temporary mechanism for influencing the runtime linker's search path, any dynamic executable that can reference this environment variable will have its search paths altered. You might see unexpected results or a degradation in performance.
Library Search Path and Order--Static Linking
Use the
-l
library compiler option to name additional libraries for the linker to search when resolving external references. For example, the option-lmylib
adds the librarylibmylib.so
orlibmylib.a
to the search list.The linker looks in the standard directory paths to find the additional
libmylib
library. The-L
option (and theLD_LIBRARY_PATH
environment variable) creates a list of paths that tell the linker where to look for libraries outside the standard paths.Were
libmylib.a
in directory/home/proj/libs
, then the option-L/home/proj/libs
would tell the linker where to look when building the executable:
demo%f77 -o pgram part1.o part2.o -L/home/proj/libs -lmylib
Command-Line Order for
-l
library OptionsFor any particular unresolved reference, libraries are searched only once, and only for symbols that are undefined at that point in the search. If you list more than one library on the command line, then the libraries are searched in the order in which they are found on the command line. Place
-l
library options as follows:
- Place the
-l
library option after any.f
,.for
,.F
,.f95
, or.o
files.- If you call functions in
lib
x, and they reference functions inlib
y, then place-l
x before-l
y.Command-Line Order for
-L
dir OptionsThe
-L
dir option adds the dir directory path to the library search list. The linker searches for libraries first in any directories specified by the-L
options and then in the standard directories. This option is useful only if it is placed preceding the
-l
library options to which it applies.Library Search Path and Order--Dynamic Linking
With dynamic libraries, changing the library search path and order of loading differs from the static case. Actual linking takes place at runtime rather than build time.
Specifying Dynamic Libraries at Build Time
When building the executable file, the linker records the paths to shared libraries in the executable itself. These search paths can be specified using the
-R
path option. This is in contrast to the-L
dir option which indicates at buildtime where to find the library specified by a-l
library option, but does not record this path into the binary executable.The directory paths that were built in when the executable was created can be viewed using the
dump
command.Example: List the directory paths built into
a.out
:
demo%f77 program.f -R/home/proj/libs -L/home/proj/libs -lmylib
demo%dump -Lv a.out | grep RPATH
[5] RPATH /home/proj/libs:/opt/SUNWspro/libSpecifying Dynamic Libraries at Runtime
At runtime, the linker determines where to find the dynamic libraries that an executable needs from:
- The value of
LD_LIBRARY_PATH
at runtime- The paths that had been specified by
-R
at the time the executable file was builtAs noted earlier, use of
LD_LIBRARY_PATH
can have unexpected side-effects and is not recommended.Fixing Errors During Dynamic Linking
When the dynamic linker cannot locate a needed library, it issues this error message:
ld.so: prog: fatal: libmylib.so: can't open file:The message indicates that the libraries are not where they are supposed to be. Perhaps you specified paths to shared libraries when the executable was built, but the libraries have subsequently been moved. For example, you might have built
a.out
with your own dynamic libraries in/
my/
libs/
, and then later moved the libraries to another directory.Use
ldd
to determine where the executable expects to find the libraries:
demo%ldd a.out
libsolib.so => /export/home/proj/libsolib.solibF77.so.4 => /opt/SUNWspro/lib/libF77.so.4libc.so.1 => /usr/lib/libc.so.1libdl.so.1 => /usr/lib/libdl.so.1If possible, move or copy the libraries into the proper directory or make a soft link to the directory (using
ln -s
) in the directory that the linker is searching. Or, it could be thatLD_LIBRARY_PATH
is not set correctly. Check thatLD_LIBRARY_PATH
includes the path to the needed libraries at runtime.Creating Static Libraries
Static library files are built from precompiled object files (.
o
files) using the ar(1) utility.The linker extracts from the library any elements whose entry points are referenced within the program it is linking, such as a subprogram, entry name, or
COMMON
block initialized in aBLOCKDATA
subprogram. These extracted elements (routines) are bound permanently into thea.out
executable file generated by the linker.Tradeoffs for Static Libraries
There are three main issues to keep in mind regarding static, as compared to dynamic, libraries and linking:
- Static libraries are more self-contained but less adaptable.
- If you bind an
a.out
executable file statically, the library routines it needs become part of the executable binary. However, if it becomes necessary to update a static library routine bound into thea.out
executable, the entirea.out
file must be relinked and regenerated to take advantage of the updated library. With dynamic libraries, the library is not part of thea.out
file and linking is done at runtime. To take advantage of an updated dynamic library, all that is required is that the new library be installed on the system.- The "elements" in a static library are individual compilation units,
.o
files.
- Since a single compilation unit (a source file) can contain more than one subprogram, these routines when compiled together become a single module in the static library. This means that all the routines in the compilation unit are loaded together into the
a.out
executable, even though only one of those subprograms was actually called. This situation can be improved by optimizing the way library routines are distributed into compilable source files. (Still, only those library modules actually referenced by the program are loaded into the executable.)- Order matters when linking static libraries.
- The linker processes its input files in the order in which they appear on the command line--left to right. When the linker decides whether or not to load an element from a library, its decision is determined by the library elements that it has already processed. This order is not only dependent on the order of the elements as they appear in the library file but also on the order in which the libraries are specified on the compile command line.
- Example: If the Fortran program is in two files,
main.f
andcrunch.f
, and only the latter accesses a library, it is an error to reference that library beforecrunch.f
orcrunch.o
:
demo%(Incorrect)f77 main.f -lmylibrary crunch.f -o myprog
demo%(Correct)f77 main.f crunch.f -lmylibrary -o myprog
Creation of a Simple Static Library
Suppose that you can distribute all the routines in a program over a group of source files and that these files are wholly contained in the subdirectory
test_lib/
.Suppose further that the files are organized in such a way that they each contain a single principal subprogram that would be called by the user program, along with any "helper" routines that the subprogram might call but that are called from no other routine in the library. Also, any helper routines called from more than one library routine are gathered together into a single source file. This gives a reasonably well-organized set of source and object files.
Assume that the name of each source file is taken from the name of the first routine in the file, which in most cases is one of the principal files in the library:
demo%cd test_lib
demo%ls
total 14 2 dropx.f 2 evalx.f 2 markx.f2 delte.f 2 etc.f 2 linkz.f 2 point.fThe lower-level "helper" routines are gathered together into the file
etc.f
. The other files can contain one or more subprograms.First, compile each of the library source files, using the
-c
option, to generate the corresponding relocatable.o
files:
Now, create the static library
testlib.a
usingar
:
demo%ar cr testlib.a *.o
To use this library, either include the library file on the compilation command or use the
-l
and-L
compilation options. The example uses the.a
file directly:
demo%cat trylib.f
C program to test testlib routinesx=21.998call evalx(x)call point(x)print*, 'value ',xenddemo%f77 -o trylib trylib.f test_lib/testlib.a
trylib.f:MAIN:demo%Notice that the main program calls only two of the routines in the library. You can verify that the uncalled routines in the library were not loaded into the executable file by looking for them in the list of names in the executable displayed by
nm
:
In the preceding example,
grep
finds entries in the list of names only for those library routines that were actually called.Another way to reference the library is through the
-l
library and-L
path options. Here, the library's name would have to be changed to conform to thelib
name.a
convention:
demo%mv test_lib/testlib.a test_lib/libtestlib.a
demo%f77 -o trylib trylib.f -Ltest_lib -ltestlib
trylib.f:MAIN:The
-l
library and-L
path options are used with libraries installed in a commonly accessible directory on the system, like/usr/local/lib
, so that other users can reference it. For example, if you leftlibtestlib.a
in/usr/local/lib
, other users could be informed to compile with the following command:
demo%f77 -o myprog myprog.f -L/usr/local/lib -ltestlib
Replacement in a Static Library
It is not necessary to recompile an entire library if only a few elements need recompiling. The
-r
option ofar
permits replacement of individual elements in a static library.Example: Recompile and replace a single routine in a static library:
demo%f77
-c point.fdemo%ar r testlib.a point.o
demo%Ordering Routines in a Static Library
To order the elements in a static library when it is being built by
ar
, use the commandslorder
(1) andtsort
(1):
demo%ar cr mylib.a 'lorder exg.o fofx.o diffz.o | tsort'
Creating Dynamic Libraries
Dynamic library files are built by the linker
ld
from precompiled object modules that can be bound into the executable file after execution begins.Another feature of a dynamic library is that modules can be used by other executing programs in the system without duplicating modules in each program's memory. For this reason, a dynamic library is also a shared library.
A dynamic library offers the following features:
- The object modules are not bound into the executable file by the linker during the compile-link sequence; such binding is deferred until runtime.
- A shared library module is bound into system memory when the first running program references it. If any subsequent running program references it, that reference is mapped to this first copy.
- Maintaining programs is easier with dynamic libraries. Installing an updated dynamic library on a system immediately affects all the applications that use it without requiring relinking of the executable.
Tradeoffs for Dynamic Libraries
Dynamic libraries introduce some additional tradeoff considerations:
- Smaller
a.out
file
- Deferring binding of the library routines until execution time means that the size of the executable file is less than the equivalent executable calling a static version of the library; the executable file does not contain the binaries for the library routines.
- Possibly smaller process memory utilization
- When several processes using the library are active simultaneously, only one copy of the memory resides in memory and is shared by all processes.
- Possibly increased overhead
- Additional processor time is needed to load and link-edit the library routines during runtime. Also, the library's position-independent coding might execute more slowly than the relocatable coding in a static library.
- Possible overall system performance improvement
- Reduced memory utilization due to library sharing should result in better overall system performance (reduced I/O access time from memory swapping).
Performance profiles among programs vary greatly from one to another. It is not always possible to determine or estimate in advance the performance improvement (or degradation) between dynamic versus static libraries. However, if both forms of a needed library are available to you, it would be worthwhile to evaluate the performance of your program with each.
Position-Independent Code and
-pic
Position-independent code (PIC) can be bound to any address in a program without requiring relocation by the link editor. Such code is inherently sharable between simultaneous processes. Thus, if you are building a dynamic, shared library, you must compile the component routines to be position-independent (by using compiler options
-pic
or-PIC
).In position-independent code, each reference to a global item is compiled as a reference through a pointer into a global offset table. Each function call is compiled in a relative addressing mode through a procedure linkage table. The size of the global offset table is limited to 8 Kbytes on SPARC processors. The
-PIC
compiler option is similar to-pic
, but-PIC
allows the global offset table to span the range of 32-bit addresses.There is a more flexible compiler flag with
f77
andf95
,-xcode=
v, for specifying the code address space of a binary object. With this compiler flag, 32-, 44-, or 64-bit absolute addresses can be generated, as well as small and large model position-independent code.-xcode=pic13
is equivalent to-pic
, and-xcode=pic32
is equivalent to-PIC
. See thef77
(1) andf95
(1) man pages, or the Fortran User's Guide, for details.Binding Options
You can specify dynamic or static library binding when you compile. These options are actually linker options, but they are recognized by the compiler and passed on to the linker.
-Bdynamic
|-Bstatic
-Bdynamic
sets the preference for shared, dynamic binding whenever possible.-Bstatic
restricts binding to static libraries only.When both static and dynamic versions of a library are available, use this option to toggle between preferences on the command line:
f77 prog.f -Bdynamic -lwells -Bstatic -lsurface
-dy
|-dn
Allows or disallows dynamic linking for the entire executable. (This option may appear on the command line only once.)
-dy
allows dynamic, shared libraries to be linked.-dn
does not allow linking of dynamic libraries.Binding in 64-Bit Environments
Some static system libraries, such as
libm.a
andlibc.a
, are not available on 64-bit Solaris operating environments. These are supplied as dynamic libraries only. Use of-dn
in these environments will result in an error indicating that some static system libraries are missing. Also, ending the compiler command line with-Bstatic
will have the same effect.To link with static versions of specific libraries, use a command line that looks something like:
f77 -o prog prog.f -Bstatic -labc -lxyz -Bdynamic
Here the user's
libabc.a
andlibxyz.a
file are linked (rather thanlibabc.so
orlibxyz.so
), and the final-Bdynamic
insures that the remaining libraries, including system libraries, and dynamically linked.In more complicated situations, it may be necessary to explicitly reference each system and user library on the link step with the appropriate
-Bstatic
or-Bdynamic
as required. First useLD_OPTIONS
set to'-Dfiles'
to obtain a listing of all the libraries needed. Then perform the link step with-nolib
(to suppress automatic linking of system libraries) and explicit references to the libraries you need. For example:
f77 -xarch=v9 -o cdf -nolib cdf.o-Bstatic -lF77 -lM77 -lsunmath -Bdynamic -lm -lc
Naming Conventions
To conform to the dynamic library naming conventions assumed by the link loader and the compilers, assign names to the dynamic libraries that you create with the prefix
lib
and the suffix.so
. For example,libmyfavs.so
could be referenced by the compiler option-lmyfavs
.The linker also accepts an optional version number suffix: for example,
libmyfavs.so.1
for version one of the library.The compiler's
-h
name option records name as the name of the dynamic library being built.A Simple Dynamic Library
Building a dynamic library requires a compilation of the source files with the
-pic
or-PIC
option and linker options-G
,-ztext
, and-h
name. These linker options are available through the compiler command line.You can create a dynamic library with the same files used in the static library example.
Example: Compile with
-pic
and other linker options:
-G
tells the linker to build a dynamic library.
-ztext
warns you if it finds anything other than position-independent code, such as relocatable text.
Example: Make an executable file
a.out
using the dynamic library:
Note that the example uses the
-R
option to bind into the executable the path (the current directory) to the dynamic library.The
file
command shows that the executable is dynamically linked.The
ldd
command shows that the executable,trylib
, uses some shared libraries, includinglibtestlib.so.1
;libf77
,libdl
, andlibc
are included by default byf77
.Libraries Provided with Sun Fortran Compilers
The table shows the libraries installed with the compilers.
See also the
math_libraries
README file for more information.VMS Library
The
libV77
library is the VMS library, which contains two special VMS routines,idate
andtime
.To use either of these routines, include the
-lV77
option.For
idate
andtime
, there is a conflict between the VMS version and the version that traditionally is available in UNIX environments. If you use the-lV77
option, you get the VMS compatible versions of theidate
andtime
routines.See the Fortran Library Reference Manual and the FORTRAN 77 Language Reference Manual for details on these routines.
POSIX
Library
There are two versions of
POSIX
bindings provided with Fortran 77:
libFposix
, which is just the bindings (-lFposix
)libFposix_c
, which does some runtime checking to make sure you are passing correct handles (-lFposix_c
)
libFposix_c
returns an error code (ENOHANDLE
).libFposix
core dumps with a segmentation fault.Of course, the checking is time-consuming, and
libFposix_c
is several times slower.Both
POSIX
libraries come in static and dynamic forms.The
POSIX
bindings provided are for IEEE Standard 1003.9-1992.IEEE 1003.9 is a binding of 1003.1-1990 to FORTRAN (X3.8-1978).
For more information, see these POSIX.1 documents:
- ISO/IEC 9945-1:1990
- IEEE Standard 1003.1-1990
- IEEE Order number SH13680
- IEEE CS Catalog number 1019
To find out precisely what
POSIX
is, you need both the 1003.9 and the POSIX.1 documents.The POSIX library for
f95
islibposix9
.Shippable Libraries
If your executable uses a Sun dynamic library that is listed in the
runtime.libraries
README file, your license includes the right to redistribute the library to your customer.This README file is located in the READMEs directory:
<install-point>
/SUNWspro/READMEs/
Do not redistribute or otherwise disclose the header files, source code, object modules, or static libraries of object modules in any form.
Sun Microsystems, Inc. Copyright information. All rights reserved. Feedback |
Library | Contents | Previous | Next | Index |