5. Integrating libtool with your package

This chapter describes how to integrate libtool with your packages so that your users can install hassle-free shared libraries.

5.1 Writing `Makefile' rules for libtool

Libtool is fully integrated with Automake (see (automake)Top section `Introduction' in The Automake Manual), starting with Automake version 1.2.

If you want to use libtool in a regular `Makefile' (or `Makefile.in'), you are on your own. If you're not using Automake 1.2, and you don't know how to incorporate libtool into your package you need to do one of the following:

1. Download Automake (version 1.2 or later) from your nearest GNU mirror, install it, and start using it.

2. Learn how to write `Makefile' rules by hand. They're sometimes complex, but if you're clever enough to write rules for compiling your old libraries, then you should be able to figure out new rules for libtool libraries (hint: examine the `Makefile.in' in the `demo' subdirectory of the libtool distribution… note especially that it was automatically generated from the `Makefile.am' by Automake).

5.2 Using Automake with libtool

Libtool library support is implemented under the `LTLIBRARIES' primary.

Here are some samples from the Automake `Makefile.am' in the libtool distribution's `demo' subdirectory.

First, to link a program against a libtool library, just use the `program_LDADD' variable:

bin_PROGRAMS = hell hell.debug

# Build hell from main.c and libhello.la
hell_SOURCES = main.c
hell_LDADD = libhello.la

# Create an easier-to-debug version of hell.
hell_debug_SOURCES = main.c
hell_debug_LDADD = libhello.la
hell_debug_LDFLAGS = -static

The flags `-dlopen' or `-dlpreopen' (see section Link mode) would fit better in the program_LDADD variable. Unfortunately, GNU automake, up to release 1.4, doesn't accept these flags in a program_LDADD variable, so you have the following alternatives:

• add them to program_LDFLAGS, and list the libraries in program_DEPENDENCIES, then wait for a release of GNU automake that accepts these flags where they belong;

• surround the flags between quotes, but then you must set program_DEPENDENCIES too:

  program_LDADD = "-dlopen" libfoo.la program_DEPENDENCIES = libfoo.la

• set and `AC_SUBST' variables DLOPEN and DLPREOPEN in `configure.in' and use `@DLOPEN@' and `@DLPREOPEN@' as replacements for the explicit flags `-dlopen' and `-dlpreopen' in `program_LDADD'. Automake will discard `AC_SUBST'ed variables from dependencies, so it will behave exactly as we expect it to behave when it accepts these flags in `program_LDADD'. But hey!, this is ugly!

You may use the `program_LDFLAGS' variable to stuff in any flags you want to pass to libtool while linking `program' (such as `-static' to avoid linking uninstalled shared libtool libraries).

Building a libtool library is almost as trivial… note the use of `libhello_la_LDFLAGS' to pass the `-version-info' (see section Library interface versions) option to libtool:

# Build a libtool library, libhello.la for installation in libdir.
lib_LTLIBRARIES = libhello.la
libhello_la_SOURCES = hello.c foo.c
libhello_la_LDFLAGS = -version-info 3:12:1

The `-rpath' option is passed automatically by Automake (except for libraries listed as noinst_LTLIBRARIES), so you should not specify it.

See Building a Shared Library: (automake)A Shared Library section `The Automake Manual' in The Automake Manual, for more information.

5.3 Configuring libtool

Libtool requires intimate knowledge of your compiler suite and operating system in order to be able to create shared libraries and link against them properly. When you install the libtool distribution, a system-specific libtool script is installed into your binary directory.

However, when you distribute libtool with your own packages (see section Including libtool in your package), you do not always know which compiler suite and operating system are used to compile your package.

For this reason, libtool must be configured before it can be used. This idea should be familiar to anybody who has used a GNU configure script. configure runs a number of tests for system features, then generates the `Makefiles' (and possibly a `config.h' header file), after which you can run make and build the package.

Libtool adds its own tests to your configure script in order to generate a libtool script for the installer's host machine.

5.3.1 The AC_PROG_LIBTOOL macro

If you are using GNU Autoconf (or Automake), you should add a call to AC_PROG_LIBTOOL to your `configure.in' file. This macro adds many new tests to the configure script so that the generated libtool script will understand the characteristics of the host:

Macro: AC_PROG_LIBTOOL

Macro: AM_PROG_LIBTOOL

Add support for the `--enable-shared' and `--disable-shared' configure flags.(4) AM_PROG_LIBTOOL was the old name for this macro, and although supported at the moment is deprecated.

By default, this macro turns on shared libraries if they are available, and also enables static libraries if they don't conflict with the shared libraries. You can modify these defaults by calling either the AC_DISABLE_SHARED or AC_DISABLE_STATIC macros:

# Turn off shared libraries during beta-testing, since they # make the build process take too long. AC_DISABLE_SHARED AC_PROG_LIBTOOL

The user may specify modified forms of the configure flags `--enable-shared' and `--enable-static' to choose whether shared or static libraries are built based on the name of the package. For example, to have shared `bfd' and `gdb' libraries built, but not shared `libg++', you can run all three configure scripts as follows:

trick$ ./configure --enable-shared=bfd,gdb

In general, specifying `--enable-shared=pkgs' is the same as configuring with `--enable-shared' every package named in the comma-separated pkgs list, and every other package with `--disable-shared'. The `--enable-static=pkgs' flag behaves similarly, but it uses `--enable-static' and `--disable-static'. The same applies to the `--enable-fast-install=pkgs' flag, which uses `--enable-fast-install' and `--disable-fast-install'.

The package name `default' matches any packages which have not set their name in the PACKAGE environment variable.

This macro also sets the shell variable LIBTOOL_DEPS, that you can use to automatically update the libtool script if it becomes out-of-date. In order to do that, add to your `configure.in':

AC_PROG_LIBTOOL AC_SUBST(LIBTOOL_DEPS)

and, to `Makefile.in' or `Makefile.am':

LIBTOOL_DEPS = @LIBTOOL_DEPS@ libtool: $(LIBTOOL_DEPS) $(SHELL) ./config.status --recheck

If you are using GNU automake, you can omit the assignment, as automake will take care of it. You'll obviously have to create some dependency on `libtool'.

Macro: AC_LIBTOOL_DLOPEN

Enable checking for dlopen support. This macro should be used if the package makes use of the `-dlopen' and `-dlpreopen' flags, otherwise libtool will assume that the system does not support dlopening. The macro must be called before AC_PROG_LIBTOOL.

Macro: AC_LIBTOOL_WIN32_DLL

This macro should be used if the package has been ported to build clean dlls on win32 platforms. Usually this means that any library data items are exported with __declspec(dllexport) and imported with __declspec(dllimport). If this macro is not used, libtool will assume that the package libraries are not dll clean and will build only static libraries on win32 hosts.

This macro must be called before AC_PROG_LIBTOOL, and provision must be made to pass `-no-undefined' to libtool in link mode from the package Makefile. Naturally, if you pass `-no-undefined', you must ensure that all the library symbols really are defined at link time!

Macro: AC_DISABLE_FAST_INSTALL

Change the default behaviour for AC_PROG_LIBTOOL to disable optimization for fast installation. The user may still override this default, depending on platform support, by specifying `--enable-fast-install'.

Macro: AC_DISABLE_SHARED

Macro: AM_DISABLE_SHARED

Change the default behaviour for AC_PROG_LIBTOOL to disable shared libraries. The user may still override this default by specifying `--enable-shared'.

Macro: AC_DISABLE_STATIC

Macro: AM_DISABLE_STATIC

Change the default behaviour for AC_PROG_LIBTOOL to disable static libraries. The user may still override this default by specifying `--enable-static'.

The tests in AC_PROG_LIBTOOL also recognize the following environment variables:

Variable: CC

The C compiler that will be used by the generated libtool. If this is not set, AC_PROG_LIBTOOL will look for gcc or cc.

Variable: CFLAGS

Compiler flags used to generate standard object files. If this is not set, AC_PROG_LIBTOOL will not use any such flags. It affects only the way AC_PROG_LIBTOOL runs tests, not the produced libtool.

Variable: CPPFLAGS

C preprocessor flags. If this is not set, AC_PROG_LIBTOOL will not use any such flags. It affects only the way AC_PROG_LIBTOOL runs tests, not the produced libtool.

Variable: LD

The system linker to use (if the generated libtool requires one). If this is not set, AC_PROG_LIBTOOL will try to find out what is the linker used by CC.

Variable: LDFLAGS

The flags to be used by libtool when it links a program. If this is not set, AC_PROG_LIBTOOL will not use any such flags. It affects only the way AC_PROG_LIBTOOL runs tests, not the produced libtool.

Variable: LIBS

The libraries to be used by AC_PROG_LIBTOOL when it links a program. If this is not set, AC_PROG_LIBTOOL will not use any such flags. It affects only the way AC_PROG_LIBTOOL runs tests, not the produced libtool.

Variable: NM

Program to use rather than checking for nm.

Variable: RANLIB

Program to use rather than checking for ranlib.

Variable: LN_S

A command that creates a link of a program, a soft-link if possible, a hard-link otherwise. AC_PROG_LIBTOOL will check for a suitable program if this variable is not set.

Variable: DLLTOOL

Program to use rather than checking for dlltool. Only meaningful for Cygwin/MS-Windows.

Variable: OBJDUMP

Program to use rather than checking for objdump. Only meaningful for Cygwin/MS-Windows.

Variable: AS

Program to use rather than checking for as. Only used on Cygwin/MS-Windows at the moment.

When you invoke the libtoolize program (see section Invoking libtoolize), it will tell you where to find a definition of AC_PROG_LIBTOOL. If you use Automake, the aclocal program will automatically add AC_PROG_LIBTOOL support to your configure script.

Nevertheless, it is advisable to include a copy of `libtool.m4' in `acinclude.m4', so that, even if `aclocal.m4' and `configure' are rebuilt for any reason, the appropriate libtool macros will be used. The alternative is to hope the user will have a compatible version of `libtool.m4' installed and accessible for aclocal. This may lead to weird errors when versions don't match.

5.4 Including libtool in your package

In order to use libtool, you need to include the following files with your package:

` config.guess'

Attempt to guess a canonical system name.

` config.sub'

Canonical system name validation subroutine script.

` install-sh'

BSD-compatible install replacement script.

` ltmain.sh'

A generic script implementing basic libtool functionality.

Note that the libtool script itself should not be included with your package. See section Configuring libtool.

You should use the libtoolize program, rather than manually copying these files into your package. Note however, that `install-sh' is not copied by libtoolize; if you use Automake, it will take care of that, otherwise you may obtain a copy from the package data directory of the installed Libtool. This may change in a future Libtool version.

5.4.1 Invoking libtoolize

The libtoolize program provides a standard way to add libtool support to your package. In the future, it may implement better usage checking, or other features to make libtool even easier to use.

The libtoolize program has the following synopsis:

libtoolize [option]…

and accepts the following options:

` --automake'

Work silently, and assume that Automake libtool support is used.

`libtoolize --automake' is used by Automake to add libtool files to your package, when AC_PROG_LIBTOOL appears in your `configure.in'.

` --copy'

` -c'

Copy files from the libtool data directory rather than creating symlinks.

` --debug'

Dump a trace of shell script execution to standard output. This produces a lot of output, so you may wish to pipe it to less (or more) or redirect to a file.

` --dry-run'

` -n'

Don't run any commands that modify the file system, just print them out.

` --force'

` -f'

Replace existing libtool files. By default, libtoolize won't overwrite existing files.

` --help'

Display a help message and exit.

` --ltdl'

Install libltdl in a subdirectory of your package.

` --ltdl-tar'

Add the file libltdl.tar.gz to your package.

` --version'

Print libtoolize version information and exit.

If libtoolize detects an explicit call to AC_CONFIG_AUX_DIR (see (autoconf)Input section `The Autoconf Manual' in The Autoconf Manual) in your `configure.in', it will put the files in the specified directory.

libtoolize displays hints for adding libtool support to your package, as well.

5.4.2 Autoconf `.o' macros

The Autoconf package comes with a few macros that run tests, then set a variable corresponding to the name of an object file. Sometimes it is necessary to use corresponding names for libtool objects.

Here are the names of variables that list libtool objects:

Variable: LTALLOCA

Substituted by AC_FUNC_ALLOCA (see Particular Function Checks: (autoconf)Particular Functions section `The Autoconf Manual' in The Autoconf Manual). Is either empty, or contains `alloca.lo'.

Variable: LTLIBOBJS

Substituted by AC_REPLACE_FUNCS (see Generic Function Checks: (autoconf)Generic Functions section `The Autoconf Manual' in The Autoconf Manual), and a few other functions.

Unfortunately, the stable release of Autoconf (2.13, at the time of this writing) does not have any way for libtool to provide support for these variables. So, if you depend on them, use the following code immediately before the call to AC_OUTPUT in your `configure.in':

LTLIBOBJS=`echo "$LIBOBJS" | sed 's/\.[^.]* /.lo /g;s/\.[^.]*$/.lo/'`
AC_SUBST(LTLIBOBJS)
LTALLOCA=`echo "$ALLOCA" | sed 's/\.[^.]* /.lo /g;s/\.[^.]*$/.lo/'`
AC_SUBST(LTALLOCA)
AC_OUTPUT(…)

5.5 Static-only libraries

When you are developing a package, it is often worthwhile to configure your package with the `--disable-shared' flag, or to override the defaults for AC_PROG_LIBTOOL by using the AC_DISABLE_SHARED Autoconf macro (see section The AC_PROG_LIBTOOL macro). This prevents libtool from building shared libraries, which has several advantages:

• compilation is twice as fast, which can speed up your development cycle,

• debugging is easier because you don't need to deal with any complexities added by shared libraries, and

• you can see how libtool behaves on static-only platforms.

You may want to put a small note in your package `README' to let other developers know that `--disable-shared' can save them time. The following example note is taken from the GIMP(5) distribution `README':

The GIMP uses GNU Libtool in order to build shared libraries on a
variety of systems. While this is very nice for making usable
binaries, it can be a pain when trying to debug a program. For that
reason, compilation of shared libraries can be turned off by
specifying the `--disable-shared' option to `configure'.

This document was generated by System Administrator on February, 19 2008 using texi2html 1.70.