Working with Unix libraries - ar command

How to Create an Object Library
As stated above, ar, the standard Unix archiver, is routinely used to create Unix object libraries. The resulting file, which ends in ".a", can therefore be referred to as an archive; however, the term library is recommended as it is more descriptive for our purposes. Archive files created by ar can contain any type of file, including text and executable files; in contrast, object libraries contain only compiled object files.

The syntax for building a library from a group of object files is

ar r


for example,

ar r libmultidim.a hypercube.o mobius_strip.o klien_bottle.o tesseract.o

will create a library in the current directory called libmultidim.a, which contains the four object files given in the example.

Note: some versions of Unix require an additional step to prepare an object library, which is building a symbol table. This operation requires the ranlib utility. Under some Unixes, including HP-UX, ar builds the symbol table automatically.

The Unix make utility has built-in rules that allow convenient building and maintaining of object libraries. ar can update an individual object file "on the fly", without having to rebuild the entire library. For this reason, updating an object library is usually as simple as editing a particular source file and typing "make". The rest is done automatically, with the help of an appropriately written Makefile.

Finding Out What's Inside an Object Library
ar has several options, and one of them, the "t" parameter, tells it to print a table of contents for the archive. For our example, typing "ar t libmultidim.a" would provide this result:

hypercube.o
mobius_strip.o
klien_bottle.o
tesseract.o

It is possible to list the symbols used by the files inside our library using the Unix nm (for "name symbols") command. When one types

nm libXXX.a

each object file within the library is shown, followed by a list of the symbols within the object file.

nm may also be used to examine the symbol tables of individual object files and executable programs. Keep in mind that for this to work, the "-g" parameter of the compiler must be used to include the symbolic information. In addition, if strip is used to remove the symbol table from an executable program, nm will no longer be able to list it's contents.

Updating an Object Library
What do we do if we need to change just one of the object files within a library? ar makes this straightforward. The same parameter used to build the library, "r", also has the function of replacing an object file in an archive with a new version.

ar r libmultidim.a hypercube.o

would remove the existing object file hypercube.o from the library, and insert an object file with the same name from the current working directory. At the same time, the library's symbol table is rebuilt to reflect any changes.

Removing and Extracting Object Files from a Library
Occasionally it is useful to remove an object file from a library. This is necessary when one of the internal files' functions are replaced by those in another file, or when an object file must be renamed. ar performs this operation using the "d" parameter. Typing

ar d libmultidim.a hypercube.o

would delete the hypercube.o object file from the library.

It is unlikely that we will have need to extract an object file from a library, but for completeness' sake, the "x" parameter provides this ability. Typing

ar x libmultidim.a hypercube.o

will extract a copy of hypercube.o into the current directory.

Note that the object file will continue to exist inside the library. Also note that if a file already existed with the same name in the current directory, it could be silently overwritten -- unless the user's shell is set to warn of this condition.

Linking An Object Library to an Application
The parameters and syntax that are used to link Unix object libraries to applications have become standardized. "-l" is used to specify each individual object library. "-L" is used to specify the pathnames on which to search for object libraries.

Library names are normally abbreviated, when specified to the compiler, using the "-l" parameter. This differs from how source and object file names are provided. Since object library names have the format "libXXX.a", the beginning "lib" and the final ".a" are stripped from the library name in the parameter specification.

For example, to link the standard math library /lib/libm.a to your program, you need only specify "-lm" in the compile/link command. The compiler uses this information to build the library name, and links it in.

Using our example library libmultidim.a, we would convert this to "-lmultidim" in the compile/link command (note that these commands will most likely be made part of an automated build process).

As mentioned previously, the paths to standard system libraries are built into the compiler and do not need to be explicitly stated. Application-specific library pathnames, however, need to be specified using the "-L" parameter, one for each pathname.

The path for each application-specific library must be placed prior to the "-l" parameter specifying the library itself. The library path specification need only be given once; the linker will thereafter search the specified path for each subsequent library in the compile/link command.

A complete specification for an example application compile & link, using the Unix math library and our example object library, would be


CC -g -I/usr/local/include -o spin_5d spin_5d.C -lm \
-L/usr/local/lib -lmultidim


For the sake of completeness, it's necessary to mention that this clever arrangement for linked library specification can be ignored, if one uses the entire path and library filename in the "-l" specification. If a single library in a nonstandard location is needed, it can be specified using, for example,


CC -g -I/usr/local/include -o spin_5d spin_5d.C -lm \
-l/usr/local/lib/libmultidim.a


If there are several libraries to include, this method can make builds difficult to write.