libtool: Linking libraries

1 
1 3.2 Linking libraries
1 =====================
1 
1 Without libtool, the programmer would invoke the 'ar' command to create
1 a static library:
1 
1      burger$ ar cru libhello.a hello.o foo.o
1      burger$
1 
1    But of course, that would be too simple, so many systems require that
1 you run the 'ranlib' command on the resulting library (to give it better
1 karma, or something):
1 
1      burger$ ranlib libhello.a
1      burger$
1 
1    It seems more natural to use the C compiler for this task, given
1 libtool's "libraries are programs" approach.  So, on platforms without
1 shared libraries, libtool simply acts as a wrapper for the system 'ar'
1 (and possibly 'ranlib') commands.
1 
1    Again, the libtool control file name ('.la' suffix) differs from the
1 standard library name ('.a' suffix).  The arguments to libtool are the
1 same ones you would use to produce an executable named 'libhello.la'
1 with your compiler (⇒Link mode):
1 
1      a23$ libtool --mode=link gcc -g -O -o libhello.la foo.o hello.o
1      *** Warning: Linking the shared library libhello.la against the
1      *** non-libtool objects foo.o hello.o is not portable!
1      ar cru .libs/libhello.a
1      ranlib .libs/libhello.a
1      creating libhello.la
1      (cd .libs && rm -f libhello.la && ln -s ../libhello.la libhello.la)
1      a23$
1 
1    Aha!  Libtool caught a common error... trying to build a library from
1 standard objects instead of special '.lo' object files.  This doesn't
1 matter so much for static libraries, but on shared library systems, it
1 is of great importance.  (Note that you may replace 'libhello.la' with
1 'libhello.a' in which case libtool won't issue the warning any more.
1 But although this method works, this is not intended to be used because
1 it makes you lose the benefits of using Libtool.)
1 
1    So, let's try again, this time with the library object files.
1 Remember also that we need to add '-lm' to the link command line because
1 'foo.c' uses the 'cos' math library function (⇒Using libtool).
1 
1    Another complication in building shared libraries is that we need to
1 specify the path to the directory wher they will (eventually) be
1 installed (in this case, '/usr/local/lib')(1):
1 
1      a23$ libtool --mode=link gcc -g -O -o libhello.la foo.lo hello.lo \
1                      -rpath /usr/local/lib -lm
1      ar cru .libs/libhello.a foo.o hello.o
1      ranlib .libs/libhello.a
1      creating libhello.la
1      (cd .libs && rm -f libhello.la && ln -s ../libhello.la libhello.la)
1      a23$
1 
1    Now, let's try the same trick on the shared library platform:
1 
1      burger$ libtool --mode=link gcc -g -O -o libhello.la foo.lo hello.lo \
1                      -rpath /usr/local/lib -lm
1      rm -fr  .libs/libhello.a .libs/libhello.la
1      ld -Bshareable -o .libs/libhello.so.0.0 .libs/foo.o .libs/hello.o -lm
1      ar cru .libs/libhello.a foo.o hello.o
1      ranlib .libs/libhello.a
1      creating libhello.la
1      (cd .libs && rm -f libhello.la && ln -s ../libhello.la libhello.la)
1      burger$
1 
1    Now that's significantly cooler... Libtool just ran an obscure 'ld'
1 command to create a shared library, as well as the static library.
1 
1    Note how libtool creates extra files in the '.libs' subdirectory,
1 rather than the current directory.  This feature is to make it easier to
1 clean up the build directory, and to help ensure that other programs
1 fail horribly if you accidentally forget to use libtool when you should.
1 
1    Again, you may want to have a look at the '.la' file to see what
1 Libtool stores in it.  In particular, you will see that Libtool uses
1 this file to remember the destination directory for the library (the
1 argument to '-rpath') as well as the dependency on the math library
1 ('-lm').
1 
1    ---------- Footnotes ----------
1 
1    (1) If you don't specify an 'rpath', then libtool builds a libtool
1 convenience archive, not a shared library (⇒Static libraries).
1