Integration with Makefile.am

Creating Libtool Libraries with Automake

Continuing in the spirit of making Libtool library management look like native static archive management, converting a Makefile.am from static archive use to Libtool library use is a matter of changing the name of the library, and adding a Libtool prefix somewhere. For example, a Makefile.am for building a static archive might be:

lib_LIBRARIES = libshell.a libshell_a_SOURCES = object.c subr.c symbol.c

This would build a static archive called libshell.a consisting of the objects object.o, subr.o and bar.o. To build an equivalent Libtool library from the same objects, you change this to:

lib_LTLIBRARIES = libshell.la libshell_la_SOURCES = object.c subr.c symbol.c

The only changes are that the library is now named with a .la suffix, and the Automake primary is now LTLIBRARIES. Note that since the name of the library has changed, you also need to use libshell_la_SOURCES, and similarly for any other Automake macros which used to refer to the old archive. As for native libraries, Libtool library names should begin with the letters lib, so that the linker will be able to find them when passed -l options.

Often you will need to add extra objects to the library as determined by configure, but this is also a mechanical process. When building native libraries, the Makefile.am would have contained:

libshell_a_LDADD = xmalloc.o @LIBOBJS@

To add the same objects to an equivalent Libtool library would require:

libshell_la_LDADD = xmalloc.lo @LTLIBOBJS@

That is, objects added to a Libtool library must be Libtool objects (with a .lo) suffix. You should add code to configure.in to ensure that LTALLOCA and LTLIBOBJS are set appropriately, See the section called Extra Macros for Libtool. Automake will take care of generating appropriate rules for building the Libtool objects mentioned in an LDADD macro.

If you want to pass any additional flags to libtool when it is building, you use the LDFLAGS macro for that library, like this:

libshell_la_LDFLAGS = -version-info 1:0:1

For a detailed list of all the available options, see Link mode: (Libtool)Link mode.

Libtool's use of -rpath has been a point of contention for some users, since it prevents you from moving shared libraries to another location in the library search path. Or, at least, if you do, all of the executables that were linked with -rpath set to the old location will need to be relinked. We (the Libtool maintainers) assert that always using -rpath is a good thing: Mainly because you can guarantee that any executable linked with -rpath will find the correct version of the library, in the rpath directory, that was intended when the executable was linked. Library versions can still be managed correctly, and will be found by the run time loader, by installing newer versions to the same directory. Additionally, it is much harder for a malicious user to leave a modified copy of system library in a directory that someone might wish to list in their LD_LIBRARY_PATH in the hope that some code they have written will be executed unexpectedly. The argument against -rpath was instigated when one of the GNU/Linux distributions moved some important system libraries to another directory to make room for a different version, and discovered that all of the executables that relied on these libraries and were linked with Libtool no longer worked. Doing this was, arguably, bad system management - the new libraries should have been placed in a new directory, and the old libraries left alone. Refusing to use -rpath incase you want to restructure the system library directories is a very weak argument.

The -rpath option (which is required for Libtool libraries) is automatically supplied by automake based on the installation directory specified with the library primary.

lib_LTLIBRARIES = libshell.la

The example would use the value of the make macro $(libdir) as the argument to -rpath, since that is where the library will be installed.

A few of the other options you can use in the library LDFLAGS are:

 Historically, the default behaviour of Libtool was as
if -no-undefined was always passed on the command
line, but it proved to be annoying to developers who had to constantly
turn it off so that  their ELF libraries could be featureful.  Now it
has to be defined explicitly if you need it.     There are is a tradeoff:
          If you don't specify -no-undefined, then
          Libtool will not build shared libraries on platforms which
          don't allow undefined symbols at link time for such a library.
          It is only safe to specify this flag when you know for
          certain that all of the libraries
          symbols are defined at link time, otherwise the
          -no-undefined link will appear to work
          until it is tried on a platform which requires all symbols to
          be defined.  Libtool will try to link the shared library in
          this case (because you told it that you have not left any
          undefined symbols), but the link will fail, because there
          are undefined symbols in spite of
          what you told Libtool.  
     For more information about this topic, see the section called Portable Library Design in the chapter called Using GNU libltdl.

Linking against Libtool Libraries with Automake

Once you have set up your Makefile.am to create some Libtool libraries. you will want to link an executable against them. You can do this easily with automake by using the program's qualified LDADD macro:

bin_PROGRAMS = shell shell_SOURCES = shell.c token.l shell_LDADD = libshell.la

This will choose either the static or shared archive from the libshell.la Libtool library depending on the target host and any Libtool mode switches metioned in the Makefile.am, or passed to configure. The chosen archive will be linked with any objects generated from the listed sources to make an executable. Note that the executable itself is a hidden file, and that in its place libtool creates a wrapper script, See the section called Executing Uninstalled Binaries in the chapter called Introducing GNU Libtool.

As with the Libtool libraries, you can pass additional switches for the libtool invocation in the qualified LDFLAGS macros to control how the shell executable is linked:

When debugging an executable, for example, it can be useful to temporarily use:

shell_LDFLAGS = -all-static

You can pass Libtool link options to all of the targets in a given directory by using the unadorned LDFLAGS macro: LDFLAGS = -static

This is best reserved for directories which have targets of the same type, all Libtool libraries or all executables for instance. The technique still works in a mixed target type directory, and libtool will ignore switches which don't make sense for particular targets. It is less maintainable, and makes it harder to understand what is going on if you do that though.