This chapter describes how to integrate libtool with your packages so that your users can install hassle-free shared libraries.
Libtool is fully integrated with Automake (see 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:
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
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 6 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, so you should not specify it.
See section `The Automake Manual' in The Automake Manual, for more information.
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 5.4 Including libtool with 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 runs a number of tests for
system features, then generates the `Makefiles' (and possibly a
`config.h' header file), after which you can run
build the package.
Libtool has its own equivalent to the
ltconfig runs a series of configuration tests, then creates a
libtool in the current directory. The
ltconfig program has the following synopsis:
ltconfig [option]... ltmain [host]
and accepts the following options:
more(1)or redirect to a file.
libtoolthat only builds static libraries.
libtoolthat builds only shared libraries if they are available. If only static libraries can be built, then this flag has no effect.
config.subto verify that host is a valid canonical host system name.
libtool, create one called file. This can be useful if you want to create libtool scripts for cross-compilers, or you want to have more than one libtool in the same directory.
ltconfigversion information and exit.
libtoolto compile and link object files.
ltmain is the
ltmain.sh shell script fragment that provides
the basic libtool functionality (see section 5.4 Including libtool with your package).
host is the canonical host system name, which by default is
guessed by running
ltconfig also recognizes the following environment variables:
Here is a simple example of using
ltconfig to configure libtool
on a NetBSD/i386 1.2 system:
burger$ ./ltconfig ltmain.sh checking host system type... i386-unknown-netbsd1.2 checking for ranlib... ranlib checking for gcc... gcc checking whether we are using GNU C... yes checking for gcc option to produce PIC... -fPIC -DPIC checking for gcc option to statically link programs... -static checking if ld is GNU ld... no checking if ld supports shared libraries... yes checking dynamic linker characteristics... netbsd1.2 ld.so checking if libtool supports shared libraries... yes checking whether to build shared libraries... yes creating libtool burger$
This example shows how to configure
libtool for cross-compiling
to a i486 GNU/Hurd 0.1 system (assuming compiler tools reside in
burger$ export PATH=/local/i486-gnu/bin:$PATH burger$ ./ltconfig ltmain.sh i486-gnu0.1 checking host system type... i486-unknown-gnu0.1 checking for ranlib... ranlib checking for gcc... gcc checking whether we are using GNU C... yes checking for gcc option to produce PIC... -fPIC -DPIC checking for gcc option to statically link programs... -static checking if ld is GNU ld... yes checking if GNU ld supports shared libraries... yes checking dynamic linker characteristics... gnu0.1 ld.so checking if libtool supports shared libraries... yes checking whether to build shared libraries... yes creating libtool burger$
If you are using GNU Autoconf (or Automake), you should add a call to
AM_PROG_LIBTOOL to your `configure.in' file. This macro
offers seamless integration between the
configure script and
ltconfigwith the correct arguments to configure the package (see section 5.3.1 Invoking
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
# Turn off shared libraries during beta-testing, since they # make the build process take too long. AM_DISABLE_SHARED AM_PROG_LIBTOOL
The user may specify modified forms of both the `--enable-shared'
and `--enable-static' flags 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
trick$ ./configure --enable-shared=bfd,gdb
In general, specifying `--enable-shared=pkgs' is the same as specifying `--enable-shared' to every package named in the comma-separated pkgs list, and `--disable-shared' to every other package. The `--enable-static=pkgs' flag behaves similarly, but it uses `--enable-static' and `--disable-static'.
The package name `default' matches any packages which have not set
their name in the
PACKAGE environment variable.
AM_PROG_LIBTOOLto disable shared libraries. The user may still override this default by specifying `--enable-shared'.
AM_PROG_LIBTOOLto disable static libraries. The user may still override this default by specifying `--enable-static'.
When you invoke the
libtoolize program (see section 5.4.1 Invoking
libtoolize), it will tell you where to find a definition of
AM_PROG_LIBTOOL. If you use Automake, the
will automatically add
AM_PROG_LIBTOOL support to your
In order to use libtool, you need to include the following files with your package:
Note that the libtool script itself should not be included with your package. See section 5.3 Configuring libtool.
You should use the
libtoolize program, rather than manually
copying these files into your package.
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.
libtoolize program has the following synopsis:
and accepts the following options:
AM_PROG_LIBTOOLappears in your `configure.in'.
more(1)or redirect to a file.
libtoolizewon't overwrite existing files.
libtoolizeversion information and exit.
libtoolize detects an explicit call to
AC_CONFIG_AUX_DIR (see 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.
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:
AC_FUNC_ALLOCA(see section `The Autoconf Manual' in The Autoconf Manual). Is either empty, or contains `alloca.lo'.
AC_REPLACE_FUNCS(see section `The Autoconf Manual' in The Autoconf Manual), and a few other functions.
Unfortunately, the most recent version of Autoconf (2.12, 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
LTLIBOBJS=`echo "$LIBOBJS" | sed 's/\.o/.lo/g'` AC_SUBST(LTLIBOBJS) LTALLOCA=`echo "$ALLOCA" | sed 's/\.o/.lo/g'` AC_SUBST(LTALLOCA) AC_OUTPUT(...)
When you are developing a package, it is often worthwhile to configure
your package with the `--disable-shared' flag, or to override the
AM_PROG_LIBTOOL by using the
Autoconf macro (see section 5.3.3 The
AM_PROG_LIBTOOL macro). This prevents libtool from
building shared libraries, which has several advantages:
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(4) 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'.
Go to the first, previous, next, last section, table of contents.