Autoconf, Automake, and Libtool: Creating Shared Libraries with libtool

| ### 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.

This document was generated by Gary V. Vaughan on February, 8 2006 using texi2html