10.2.2 Creating Shared Libraries

From Libtool's point of view, the term `shared library' is somewhat of a misnomer. Since Libtool is intended to abstract away the details of library building, it doesn't matter whether Libtool is building a shared library or a static archive. Of course, Libtool will always try to build a shared library by default on the platforms to which it has been ported (see section B. PLATFORMS), but will equally fall back to building a static archive if the host architecture does not support shared libraries, or if the project developer deliberately configures Libtool to always build static archives only. These libraries are more properly called `Libtool libraries'; the underlying native library will usually be a shared library, except as described above.

To create a Libtool library on my HP-UX host, or indeed anywhere else that libtool works, run the following commands:

$ rm hello.o libhello.a $ libtool gcc -c hello.c mkdir .libs gcc -c -fPIC -DPIC hello.c -o .libs/hello.lo gcc -c hello.c -o hello.o >/dev/null 2>&1 mv -f .libs/hello.lo hello.lo $ ls hello.c hello.lo hello.o $ libtool gcc -rpath /usr/local/lib -o libhello.la hello.lo rm -fr .libs/libhello.la .libs/libhello.* .libs/libhello.* /opt/gcc-lib/hp821/2.7.0/ld -b +h libhello.sl.0 +b /usr/local/lib \ -o .libs/libhello.sl.0.0 hello.lo (cd .libs && rm -f libhello.sl.0 && ln -s libhello.sl.0.0 libhello.sl.0) (cd .libs && rm -f libhello.sl && ln -s libhello.sl.0.0 libhello.sl) ar cru .libs/libhello.a hello.o ranlib .libs/libhello.a creating libhello.la (cd .libs && rm -f libhello.la && ln -s ../libhello.la libhello.la) $ ls hello.c hello.lo hello.o libhello.la

This example illustrates several features of libtool. Compare the command line syntax with the previous example (see section 10.2 The Libtool Library). They are both very similar. Notice, however, that when compiling the `hello.c' source file, libtool creates two objects. The first, `hello.lo', is the Libtool object which we use for Libtool libraries, and the second, `hello.o' is a standard object. On HP-UX, libtool knows that Libtool objects should be compiled with position independent code, hence the extra switches when creating the first object.

When you run libtool from the command line, you must also specify a compiler for it to call. Similarly when you create a libtool script with ltconfig, a compiler is chosen and interrogated to discover what characteristics it has. See section 10.1 Creating libtool.

Prior to release 1.4 of Libtool, ltconfig probed the build machine for a suitable compiler, by searching first for gcc and then cc. The functionality of ltconfig is being migrated into the `AC_PROG_LIBTOOL' macro, such that there will be no ltconfig script in Libtool release 1.5. The current release is part way between the two. In all cases, you can specify a particular compiler by setting the `CC' environment variable.

It is important to continue to use the same compiler when you run libtool as the compiler that was used when you created the libtool script. If you create the script with `CC' set to gcc, and subsequently try to compile using, say:

$ libtool c89 -rpath /usr/local/lib -c hello.c

libtool will try to call c89 using the options it discovered for gcc. Needless to say, that doesn't work!

The link command specifies a Libtool library target, `libhello.la', compiled from a single Libtool object, `hello.lo'. Even so, libtool knows how to build both static and shared archives on HP-UX -- underneath the libtool abstraction both are created. libtool also understands the particulars of library linking on HP-UX: the static archive, `libhello.a', is blessed; the system (and compiler) dependent compiler and linker flags, versioning scheme and .sl extension are utilised for the shared archive, `libhello.sl'. On another host, all of these details may be completely different, yet with exactly the same invocation, libtool will call the native tools with the appropriate options to achieve the same result. Try it on your own machines to see any differences.

It is the `-rpath' switch that tells libtool that you want to build a Libtool library (with both the shared and static components where possible). If you omit the `-rpath' switch, libtool will build a convenience library instead, see Creating convenience Libraries. The `-rpath' switch is doubly important, because it tells libtool that you intend to install `libhello.la' in `/usr/local/lib'. This allows libtool to finalize the library correctly after installation on the architectures that need it, see 10.6 Installing a Library.

Finally, notice that only the Libtool library, `libhello.la', is visible after a successful link. The various files which form the local implementation details of the Libtool library are in a hidden subdirectory, but in order for the abstraction to work cleanly you shouldn't need to worry about these too much.