Sun Studio 12: Fortran Programming Guide

4.4 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 a BLOCKDATA subprogram. These extracted elements (routines) are bound permanently into the a.out executable file generated by the linker.

4.4.1 Tradeoffs for Static Libraries

There are three main issues to keep in mind regarding static, as compared to dynamic, libraries and linking:

Example: If the Fortran program is in two files, main.f and crunch.f, and only the latter accesses a library, it is an error to reference that library before crunch.f or crunch.o:

demo% f95 main.f -lmylibrary crunch.f -o myprog


demo% f95 main.f crunch.f -lmylibrary -o myprog    


4.4.2 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.f
   2 delte.f      2 etc.f        2 linkz.f      2 point.f

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

demo% f95 -c *.f
demo% ls
total 42
 2 dropx.f     4 etc.o      2 linkz.f    4 markx.o 
 2 delte.f     4 dropx.o    2 evalx.f    4 linkz.o     2 point.f
 4 delte.o     2 etc.f      4 evalx.o    2 markx.f     4 point.o

Now, create the static library testlib.a using ar:

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 routines
            call evalx(x)
            call point(x)
            print*, ’value ’,x
demo% f95 -o trylib trylib.f test_lib/testlib.a

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:

demo% nm trylib | grep FUNC | grep point
[146]      |     70016|     152|FUNC |GLOB |0    |8      |point_
demo% nm trylib | grep FUNC | grep evalx
[165]      |     69848|     152|FUNC |GLOB |0    |8      |evalx_
demo% nm trylib | grep FUNC | grep delte
demo% nm trylib | grep FUNC | grep markx
demo% ..etc

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 -llibrary and -Lpath options. Here, the library’s name would have to be changed to conform to the libname.a convention:

demo% mv test_lib/testlib.a test_lib/libtestlib.a
demo% f95 -o trylib trylib.f -Ltest_lib -ltestlib

The -llibrary and -Lpath 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 left libtestlib.a in /usr/local/lib, other users could be informed to compile with the following command:

demo% f95 -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 of ar permits replacement of individual elements in a static library.

Example: Recompile and replace a single routine in a static library:

demo% f95 -c point.f
demo% ar -r testlib.a point.o Ordering Routines in a Static Library

To order the elements in a static library when it is being built by ar, use the commands lorder(1) and tsort(1):

demo% ar -cr mylib.a ’lorder exg.o fofx.o diffz.o | tsort’