libtool: Static libraries

1 
1 3.7 Linking static libraries
1 ============================
1 
1 Why return to 'ar' and 'ranlib' silliness when you've had a taste of
1 libtool?  Well, sometimes it is desirable to create a static archive
1 that can never be shared.  The most frequent case is when you have a set
1 of object files that you use to build several different libraries.  You
1 can create a "convenience library" out of those objects, and link
1 against that with the other libraries, instead of listing all the object
1 files every time.
1 
1    If you just want to link this convenience library into programs, then
1 you could just ignore libtool entirely, and use the old 'ar' and
1 'ranlib' commands (or the corresponding GNU Automake '_LIBRARIES'
1 rules).  You can even install a convenience library using GNU Libtool,
1 though you probably don't want to and hence GNU Automake doesn't allow
1 you to do so.
1 
1      burger$ libtool --mode=install ./install-sh -c libhello.a \
1                      /local/lib/libhello.a
1      ./install-sh -c libhello.a /local/lib/libhello.a
1      ranlib /local/lib/libhello.a
1      burger$
1 
1    Using libtool for static library installation protects your library
1 from being accidentally stripped (if the installer used the '-s' flag),
1 as well as automatically running the correct 'ranlib' command.
1 
1    But libtool libraries are more than just collections of object files:
1 they can also carry library dependency information, which old archives
1 do not.  If you want to create a libtool static convenience library, you
1 can omit the '-rpath' flag and use '-static' to indicate that you're
1 only interested in a static library.  When you link a program with such
1 a library, libtool will actually link all object files and dependency
1 libraries into the program.
1 
1    If you omit both '-rpath' and '-static', libtool will create a
1 convenience library that can be used to create other libtool libraries,
1 even shared ones.  Just like in the static case, the library behaves as
1 an alias to a set of object files and dependency libraries, but in this
1 case the object files are suitable for inclusion in shared libraries.
1 But be careful not to link a single convenience library, directly or
1 indirectly, into a single program or library, otherwise you may get
1 errors about symbol redefinitions.
1 
1    The key is remembering that a convenience library contains PIC
1 objects, and can be linked where a list of PIC objects makes sense; i.e.
1 into a shared library.  A static convenience library contains non-PIC
1 objects, so can be linked into an old static library, or a program.
1 
1    When GNU Automake is used, you should use 'noinst_LTLIBRARIES'
1 instead of 'lib_LTLIBRARIES' for convenience libraries, so that the
1 '-rpath' option is not passed when they are linked.
1 
1    As a rule of thumb, link a libtool convenience library into at most
1 one libtool library, and never into a program, and link libtool static
1 convenience libraries only into programs, and only if you need to carry
1 library dependency information to the user of the static convenience
1 library.
1 
1    Another common situation where static linking is desirable is in
1 creating a standalone binary.  Use libtool to do the linking and add the
1 '-all-static' flag.
1