.TI F77/USERLIBS "Sep. 15, 1984"
Making Random Libraries from Object Files

A library is a single file which contains many different object files
plus an index to the contents of the library.  In UNIX, libraries are
"archives" and have names ending in ".a".  When loading, only the
needed object files are loaded from libraries mentioned in the f77
command.  To load a program requiring object files from library file
"mylib.a" in the current directory, type:

	f77 prog.o sub1.o ... mylib.a

This loads the object files prog.o, sub1.o, etc. and then loads those
object files in mylib.a that prog.o, sub1.o, ... reference.

Library names are listed at the end of the f77 command because
object files in the libraries are loaded only if the object files
are referenced by previously loaded object files.

The "ar" command creates and maintains archives on UNIX.  Here
is a simple example that compiles three subroutines and adds them
to the archive mylib.a:

.nf
	f77 -c sub1.f sub2.f sub3.f 
	ar uv mylib.a  sub1.o sub2.o sub3.o
.fi

Ar will respond with "a - sub.o" when a file is first inserted (appended) into
the archive.
We could use the same ar command to replace already existing
object files in the archive.  Ar responds with "r - sub.o" when a file is
updated (replaced) in the archive.

Use ranlib to add a random table of contents to the archive, converting it to a
library:

	ranlib mylib.a

To see what .o files are in a library or archive, type:

	ar tv mylib.a

To see what subprograms, entry points, and common blocks are referenced
by the .o files in an archive, type:

	nm -g mylib.a

The loader checks whether the random index of a library is up to date
or not by comparing the date within the file to the modification date
of the file.  Because of this, if you use the 'cp' command to make a
second copy of a library, the loader thinks the random index for the
library is out of date, ignores it and issues a warning:

.nf
	% cp  libnew.a  mylib.a
	% f77  prog.o  mylib.a
	ld:mylib.a: warning: table of contents for archive is out
	   of date; rerun ranlib(1)
.fi

Instead, either use the 'mv' command if you just want to change the
name or path of the library,
or use the 'tar' command if you really want to make an identical copy.
To use 'tar', first move into the directory containing the library.
Then issue the command:

	tar cBf - libnew.a | ( cd ~/newdir ; tar xBf - libnew.a )

This copies libnew.a to ~/newdir/libnew.a.  Tar creates the new file
with the same modification date as the original file so that you do
not need to rerun ranlib.  Notice that the name of the library, libnew.a,
appears twice in the command line and must be identical in both positions.
If you want the copy of the library to have a different name, follow
the tar with a mv command.

To copy a library across systems, use tar together with rsh; e.g. to
copy mylib.a on opal to ~/mybin/mylib.a on populi, type the
following on opal:

.nf
	tar cBf - mylib.a \\
		 | rsh populi "( cd mybin; tar xBf - mylib.a )"
.fi

For large libraries, you may want to check if there were transmission errors
by comparing the copy to the original:

	rsh populi cat mylib.a | cmp - mylib.a

For more information, see ar(1), ld(1), nm(1), ranlib(1), and rsh(1) in the
UNIX Programmer's Manual.

For information of importance in dealing with large libraries, see "help
f77 biglibs".
