C++ Cookbook

1.3. Building a Static Library from the Command Line

Problem

You wish to use your command-line tools to build a static library from a collection of C++ source files, such as those listed in Example 1-1.

Solution

First, use your compiler to compile the source files into object files. If your source files include headers located in other directories, you may need to use the -I option to instruct your compiler where to search for headers; for more information, see Recipe 1.5. Second, use your archiver to combine the object files into a static library.

To compile each of the three source files from Example 1-1, use the command lines listed in Table 1-8, modifying the names of the input and output files as needed. To combine the resulting object files into a static library, use the commands listed in Table 1-10.

Table 1-10. Commands for creating the archive libjohnpaul.lib or libjohnpaul.a

Toolset	Command line
GCC (Unix)Intel (Linux)Comeau (Unix)	ar ru libjohnpaul.a john.o paul.o johnpaul.oranlib libjohnpaul.a
GCC (Windows)	ar ru libjohnpaul.a john.o paul.o johnpaul.o
Visual C++Comeau (with Visual C++)	lib -nologo -out:libjohnpaul.lib john.obj paul.obj johnpaul.obj
Intel (Windows)	xilib -nologo /out:libjohnpaul.lib john.obj paul.obj johnpaul.obj
Metrowerks (Windows)	mwld -library -o libjohnpaul.lib john.obj paul.obj johnpaul.obj
Metrowerks (Mac OS X)	mwld -library -o libjohnpaul.a john.o paul.o johnpaul.o
Borland	tlib libjohnpaul.lib /u /a /C +john +paul +johnpaul
Digital Mars	lib -c -n libjohnpaul.lib john.obj paul.obj johnpaul.obj

For example, to compile john.cpp, paul.cpp, and johnpaul.cpp into object files using GCC, change to the directory johnpaul and enter the following commands to produce the object files john.o, paul.o, and johnpaul.o:

$ g++ -c -o john.o john.cpp
$ g++ -c -o paul.o paul.cpp
$ g++ -c -o johnpaul.o johnpaul.cpp

Now link the object files into a static library as follows:

$ ar ru libjohnpaul.a john.o paul.o johnpaul.o
$ ranlib libjohnpaul.a

Discussion

With GCC on Unix you use two separate commands to create a static library: first, you invoke the archiver ar, then you invoke a tool named ranlib. The ru option tells ar to add the given object files to the specified archive if there are no existing archive members with the same names, but to update an existing archive member only if the given object file is newer than the existing member. Traditionally, after an archive was created or updated, the tool ranlib was used to create or update the archive’s symbol table, i.e., the index of the symbols that appear in the various object files it contains. Today, on many systems, the archiver ar takes care of building or updating the symbol table by itself, so running ranlib is not necessary. In particular, this is true for the GNU version of ar. On some systems, however, the GCC compiler may be used in conjunction with a non-GNU version of ar; for this reason, it’s best to run ranlib just to be safe.

As you can see from Table 1-10, the Borland archiver tlib uses a slightly unusual syntax: the plus signs before the object files tell tlib to add these object files to the library. You should be able to understand all the other command lines fairly easily.

Tip

With some toolsets, the linker can be used as an archiver by passing an appropriate command-line option. With other toolsets a separate archiver must be used.

See Also

Recipe 1.8, Recipe 1.11, and Recipe 1.16