GNU Info

(libtool.info)Linking libraries

---

Next: Linking executables Prev: Creating object files Up: Using libtool

---

Enter node , (file) or (file)node

Linking libraries
=================

   Without libtool, the programmer would invoke the `ar' command to
create a static library:

     burger$ ar cru libhello.a hello.o foo.o
     burger$

   But of course, that would be too simple, so many systems require that
you run the `ranlib' command on the resulting library (to give it
better karma, or something):

     burger$ ranlib libhello.a
     burger$

   It seems more natural to use the C compiler for this task, given
libtool's "libraries are programs" approach.  So, on platforms without
shared libraries, libtool simply acts as a wrapper for the system `ar'
(and possibly `ranlib') commands.

   Again, the libtool library name differs from the standard name (it
has a `.la' suffix instead of a `.a' suffix).  The arguments to libtool
are the same ones you would use to produce an executable named
`libhello.la' with your compiler (Note: Link mode):

     a23$ libtool gcc -g -O -o libhello.la foo.o hello.o
     libtool: cannot build libtool library `libhello.la' from non-libtool \
                     objects
     a23$

   Aha!  Libtool caught a common error... trying to build a library
from standard objects instead of library objects.  This doesn't matter
for static libraries, but on shared library systems, it is of great
importance.

   So, let's try again, this time with the library object files.
Remember also that we need to add `-lm' to the link command line because
`foo.c' uses the `cos' math library function (Note: Using libtool).

   Another complication in building shared libraries is that we need to
specify the path to the directory in which they (eventually) will be
installed (in this case, `/usr/local/lib')(1):

     a23$ libtool gcc -g -O -o libhello.la foo.lo hello.lo \
                     -rpath /usr/local/lib -lm
     mkdir .libs
     ar cru .libs/libhello.a foo.o hello.o
     ranlib .libs/libhello.a
     creating libhello.la
     a23$

   Now, let's try the same trick on the shared library platform:

     burger$ libtool gcc -g -O -o libhello.la foo.lo hello.lo \
                     -rpath /usr/local/lib -lm
     mkdir .libs
     ld -Bshareable -o .libs/libhello.so.0.0 foo.lo hello.lo -lm
     ar cru .libs/libhello.a foo.o hello.o
     ranlib .libs/libhello.a
     creating libhello.la
     burger$

   Now that's significantly cooler... libtool just ran an obscure `ld'
command to create a shared library, as well as the static library.

   Note how libtool creates extra files in the `.libs' subdirectory,
rather than the current directory.  This feature is to make it easier
to clean up the build directory, and to help ensure that other programs
fail horribly if you accidentally forget to use libtool when you should.

   ---------- Footnotes ----------

   (1) If you don't specify an `rpath', then libtool builds a libtool
convenience archive, not a shared library (Note: Static libraries).