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:

• 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 the a.out executable, the entire a.out file must be relinked and regenerated to take advantage of the updated library. With dynamic libraries, the library is not part of the a.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 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

(Incorrect)

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

(Correct)

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
demo%

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

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

4.4.2.1 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

4.4.2.2 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’