Autoconf, Automake, and Libtool: Installing a Library

| ## 10.6 Installing a Library Now that the library and an executable which links with it have been successfully built, they can be installed. For the sake of this example I will `cp` the objects to their destination, though `libtool` would be just as happy if I were to use `install` with the long, requisite list of parameters. It is important to install the library to the ``-rpath'` destination which was specified when it was linked earlier, or at least that it be visible from that location when the runtime loader searches for it. This rule is not enforced by `libtool`, since it is often desirable to install libraries to a staging(17) area. Of course, the package must ultimately install the library to the specified ``-rpath'` destination for it to work correctly, like this:
    $ libtool cp libtrim.la /usr/local/lib
    cp .libs/libtrim.sl.0.0 /usr/local/lib/libtrim.sl.0.0
    (cd /usr/local/lib && rm -f libtrim.sl.0 && \
    ln -s libtrim.sl.0.0 libtrim.sl.0)
    (cd /usr/local/lib && rm -f libtrim.sl && \
    ln -s libtrim.sl.0.0 libtrim.sl)
    chmod 555 /usr/local/lib/libtrim.sl.0.0
    cp .libs/libtrim.lai /usr/local/lib/libtrim.la
    cp .libs/libtrim.a /usr/local/lib/libtrim.a
    ranlib /usr/local/lib/libtrim.a
    chmod 644 /usr/local/lib/libtrim.a
    ----------------------------------------------------------------------
    Libraries have been installed in:
       /usr/local/lib

    If you ever happen to want to link against installed libraries
    in a given directory, LIBDIR, you must either use libtool, and
    specify the full pathname of the library, or use -LLIBDIR
    flag during linking and do at least one of the following:
       - add LIBDIR to the SHLIB_PATH environment variable
         during execution
       - use the -Wl,+b -Wl,LIBDIR linker flag

    See any operating system documentation about shared libraries for
    more information, such as the ld(1) and ld.so(8) manual pages.
    ----------------------------------------------------------------------
Again, `libtool` takes care of the details for you. Both the static and shared archives are copied into the installation directory and their access modes are set appropriately. `libtool` blesses the static archive again with `ranlib`, which would be easy to forget without the benefit of `libtool`, especially if I develop on a host where the library will continue to work without this step. Also, `libtool` creates the necessary links for the shared archive to conform with HP-UXs library versioning rules. Compare this to what you see with the equivalent commands running on GNU/Linux to see how `libtool` applies these rules according to the requirements of its host. The block of text `libtool` shows at the end of the installation serves to explain how to link executables against the newly installed library on HP-UX and how to make sure that the executables linked against it will work. Of course, the best way to ensure this is to use `libtool` to perform the linking. I'll leave the details of linking against an installed Libtool library as an exercise - everything you need to know can be extrapolated from the example of linking against an uninstalled Libtool library, See section 10.3 Linking an Executable. On some architectures, even shared archives need to be blessed on installation. For example, GNU/Linux requires that `ldconfig` be run when a new library is installed. Typically, a library will be installed to its target destination after being built, in which case `libtool` will perform any necessary blessing during installation. Sometimes, when building a binary package for installation on another machine, for example, it is not desirable to perform the blessing on the build machine. No problem, `libtool` takes care of this too! `libtool` will detect if you install the library to a destination other than the one specified in the ``-rpath'` argument passed during the archive link, and will simply remind you what needs to be done before the library can be used:
    $ mkdir -p /usr/local/stow/hello-1.0/lib
    $ libtool cp libtrim.la /usr/local/stow/hello-1.0/lib
    cp .libs/libtrim.sl.0.0 /usr/local/stow/hello-1.0/lib/libtrim.sl.0.0
    (cd /usr/local/stow/hello-1.0/lib && rm -f libtrim.sl.0 && \
    ln -s libtrim.sl.0.0 libtrim.sl.0)
    (cd /usr/local/stow/hello-1.0/lib && rm -f libtrim.sl && \
    ln -s libtrim.sl.0.0 libtrim.sl)
    chmod 555 /usr/local/stow/hello-1.0/lib/libtrim.sl.0.0
    cp .libs/libtrim.lai /usr/local/stow/hello-1.0/lib/libtrim.la
    cp .libs/libtrim.a /usr/local/stow/hello-1.0/lib/libtrim.a
    ranlib /usr/local/stow/hello-1.0/lib/libtrim.a
    chmod 644 /usr/local/stow/hello-1.0/lib/libtrim.a
    libtool: install: warning: remember to run
    libtool: install: warning: libtool --finish /usr/local/lib
If you will make the installed libraries visible in the destination directory with symbolic links, you need to do whatever it is you do to make the library visible, and then bless the library in that location with the `libtool --finish /usr/local/lib` command:
    $ cd /usr/local/stow
    $ stow hello-1.0
    $ libtool --finish /usr/local/lib
If you are following the examples so far, you will also need to install the Libtool library, ``libhello.la'`, before you move on to the next section:
    $ libtool cp libhello.la /usr/local/lib
    cp .libs/libhello.sl.0.0 /usr/local/lib/libhello.sl.0.0
    (cd /usr/local/lib && rm -f libhello.sl.0 && \
    ln -s libhello.sl.0.0 libhello.sl.0)
    (cd /usr/local/lib && rm -f libhello.sl && \
    ln -s libhello.sl.0.0 libhello.sl)
    chmod 555 /usr/local/lib/libhello.sl.0.0
    cp .libs/libhello.lai /usr/local/lib/libhello.la
    cp .libs/libhello.a /usr/local/lib/libhello.a
    ranlib /usr/local/lib/libhello.a
    chmod 644 /usr/local/lib/libhello.a
    ----------------------------------------------------------------------
    Libraries have been installed in:
       /usr/local/lib

    If you ever happen to want to link against installed libraries
    in a given directory, LIBDIR, you must either use libtool, and
    specify the full pathname of the library, or use -LLIBDIR
    flag during linking and do at least one of the following:
       - add LIBDIR to the SHLIB_PATH environment variable
         during execution
       - use the -Wl,+b -Wl,LIBDIR linker flag

    See any operating system documentation about shared libraries for
    more information, such as the ld(1) and ld.so(8) manual pages.
    ----------------------------------------------------------------------
Once a Libtool library is installed, binaries which link against it will hardcode the path to the Libtool library, as specified with the ``-rpath'` switch when the library was built. `libtool` always encodes the installation directory into a Libtool library for just this purpose. Hardcoding directories in this way is a good thing, because binaries linked against such libraries will continue to work if there are several incompatible versions of the library visible to the runtime loader (say a Trojan ``libhello'` in a user's `LD_LIBRARY_PATH`, or a test build of the next release). The disadvantage to this system is that if you move libraries to new directories, executables linked in this way will be unable to find the libraries they need. Moving any library is a bad idea however, doubly so for a Libtool library which has its installation directory encoded internally, so the way to avoid problems of this nature is to not move libraries around after installation!

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