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!