Go to the first, previous, next, last section, table of contents.
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
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:
program_LDADD = "-dlopen" libfoo.la program_DEPENDENCIES = libfoo.la
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 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 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.
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:
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'.
AC_PROG_LIBTOOL.
__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!
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'.
AC_PROG_LIBTOOL to disable
shared libraries. The user may still override this default by
specifying `--enable-shared'.
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:
libtool. If
this is not set, AC_PROG_LIBTOOL will look for gcc or
cc.
AC_PROG_LIBTOOL will not use any such flags. It affects
only the way AC_PROG_LIBTOOL runs tests, not the produced
libtool.
AC_PROG_LIBTOOL will
not use any such flags. It affects only the way AC_PROG_LIBTOOL
runs tests, not the produced libtool.
libtool requires one).
If this is not set, AC_PROG_LIBTOOL will try to find out what is
the linker used by CC.
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.
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.
nm.
ranlib.
AC_PROG_LIBTOOL will check for a suitable
program if this variable is not set.
dlltool. Only meaningful
for Cygwin/MS-Windows.
objdump. Only meaningful
for Cygwin/MS-Windows.
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.
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 Configuring libtool.
You should use the libtoolize program, rather than manually
copying these files into your package.
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:
AC_PROG_LIBTOOL appears in your
`configure.in'.
less (or
more) or redirect to a file.
libtoolize won't
overwrite existing files.
libtoolize version information and exit.
If 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 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(...)
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:
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'.
Go to the first, previous, next, last section, table of contents.