libtool.texi

GNU libtool 是一个通用库支持脚本

The following components of @var{mode-args} are treated specially:

@table @samp
@item -dlopen @var{file}
Add the directory containing @var{file} to the library path.
@end table

This mode sets the library path environment variable according to any
@samp{-dlopen} flags.

If any of the @var{args} are libtool executable wrappers, then they are
translated into the name of their corresponding uninstalled binary, and
any of their required library directories are added to the library path.

@node Install mode
@section Install mode
@cindex install mode
@cindex mode, install

In @dfn{install} mode, libtool interprets most of the elements of
@var{mode-args} as an installation command beginning with
@code{cp}, or a BSD-compatible @code{install} program.

The following components of @var{mode-args} are treated specially:

@table @samp
@item -inst-prefix @var{inst-prefix-dir}
When installing into a temporary staging area, rather than the
final @var{prefix}, this argument is used to reflect the
temporary path, in much the same way @code{automake} uses
@var{DESTDIR}.  For instance, if @var{prefix} is @code{/usr/local},
but @var{inst-prefix-dir} is @code{/tmp}, then the object will be
installed under @code{/tmp/usr/local/}.  If the installed object
is a libtool library, then the internal fields of that library
will reflect only @var{prefix}, not @var{inst-prefix-dir}:

@example
# Directory that this library needs to be installed in:
libdir='/usr/local/lib'
@end example

not

@example
# Directory that this library needs to be installed in:
libdir='/tmp/usr/local/lib'
@end example

@code{inst-prefix} is also used to insure that if the installed
object must be relinked upon installation, that it is relinked
against the libraries in @var{inst-prefix-dir}/@var{prefix},
not @var{prefix}.

In truth, this option is not really intended for use when calling
libtool directly; it is automatically used when @code{libtool --mode=install}
calls @code{libtool --mode=relink}.  Libtool does this by
analyzing the destination path given in the original
@code{libtool --mode=install} command and comparing it to the
expected installation path established during @code{libtool --mode=link}.

Thus, end-users need change nothing, and @code{automake}-style
@code{make install DESTDIR=/tmp} will Just Work(tm).
@end table

The rest of the @var{mode-args} are interpreted as arguments to the
@code{cp} or @code{install} command.

The command is run, and any necessary unprivileged post-installation
commands are also completed.

@node Finish mode
@section Finish mode
@cindex finish mode
@cindex mode, finish

@dfn{Finish} mode helps system administrators install libtool libraries
so that they can be located and linked into user programs.

Each @var{mode-arg} is interpreted as the name of a library directory.
Running this command may require superuser privileges, so the
@samp{--dry-run} option may be useful.

@node Uninstall mode
@section Uninstall mode
@cindex uninstall mode
@cindex mode, uninstall

@dfn{Uninstall} mode deletes installed libraries, executables and objects.

The first @var{mode-arg} is the name of the program to use to delete
files (typically @file{/bin/rm}).

The remaining @var{mode-args} are either flags for the deletion program
(beginning with a `-'), or the names of files to delete.

@node Clean mode
@section Clean mode
@cindex clean mode
@cindex mode, clean

@dfn{Clean} mode deletes uninstalled libraries, executables, objects
and libtool's temporary files associated with them.

The first @var{mode-arg} is the name of the program to use to delete
files (typically @file{/bin/rm}).

The remaining @var{mode-args} are either flags for the deletion program
(beginning with a `-'), or the names of files to delete.

@node Integrating libtool
@chapter 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.

@menu
* Makefile rules::              Writing @file{Makefile} rules for libtool.
* Using Automake::              Automatically supporting libtool.
* Configuring::                 Configuring libtool for a host system.
* Distributing::                What files to distribute with your package.
* Static-only libraries::       Sometimes shared libraries are just a pain.
@end menu

@node Makefile rules
@section Writing @file{Makefile} rules for libtool
@cindex Makefile
@cindex Makefile.am
@cindex Makefile.in

Libtool is fully integrated with Automake (@pxref{Top,, Introduction,
automake, The Automake Manual}), starting with Automake version 1.2.

If you want to use libtool in a regular @file{Makefile} (or
@file{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:

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

@item
Learn how to write @file{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 @file{Makefile.in} in the @file{demo}
subdirectory of the libtool distribution@dots{} note especially that it
was automatically generated from the @file{Makefile.am} by Automake).
@end enumerate

@node Using Automake
@section Using Automake with libtool

@vindex LTLIBRARIES
Libtool library support is implemented under the @samp{LTLIBRARIES}
primary.

Here are some samples from the Automake @file{Makefile.am} in the
libtool distribution's @file{demo} subdirectory.

First, to link a program against a libtool library, just use the
@samp{program_LDADD} variable:

@example
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
@end example

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

@itemize @bullet
@item
add them to @var{program_LDFLAGS}, and list the libraries in
@var{program_DEPENDENCIES}, then wait for a release of GNU automake that
accepts these flags where they belong;

@item
surround the flags between quotes, but then you must set
@var{program_DEPENDENCIES} too:

@example
program_LDADD = "-dlopen" libfoo.la
program_DEPENDENCIES = libfoo.la
@end example

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

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

Building a libtool library is almost as trivial@dots{} note the use of
@samp{libhello_la_LDFLAGS} to pass the @samp{-version-info}
(@pxref{Versioning}) option to libtool:

@example
# 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
@end example

The @samp{-rpath} option is passed automatically by Automake (except for
libraries listed as @code{noinst_LTLIBRARIES}), so you
should not specify it.

@xref{A Shared Library, Building a Shared Library, The Automake Manual,
automake, The Automake Manual}, for more information.

@node Configuring
@section Configuring libtool
@cindex 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
(@pxref{Distributing}), you do not always know which compiler suite and
operating system are used to compile your package.

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

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

@menu
* AC_PROG_LIBTOOL::             Configuring @code{libtool} in @file{configure.in}.
@end menu

@node AC_PROG_LIBTOOL
@subsection The @code{AC_PROG_LIBTOOL} macro

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

@defmac AC_PROG_LIBTOOL
@defmacx AM_PROG_LIBTOOL
Add support for the @samp{--enable-shared} and @samp{--disable-shared}
@code{configure} flags.@footnote{@code{AC_PROG_LIBTOOL} requires that
you define the @file{Makefile} variable @code{top_builddir} in your
@file{Makefile.in}.  Automake does this automatically, but Autoconf
users should set it to the relative path to the top of your build
directory (@file{../..}, for example).}  @code{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
@code{AC_DISABLE_SHARED} or @code{AC_DISABLE_STATIC} macros:

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

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

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

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

The package name @samp{default} matches any packages which have not set
their name in the @code{PACKAGE} environment variable.

This macro also sets the shell variable @var{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 @file{configure.in}:

@example
AC_PROG_LIBTOOL
AC_SUBST(LIBTOOL_DEPS)
@end example

and, to @file{Makefile.in} or @file{Makefile.am}:

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

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 @file{libtool}.

@end defmac

@defmac AC_LIBTOOL_DLOPEN
Enable checking for dlopen support. This macro should be used if
the package makes use of the @samp{-dlopen} and @samp{-dlpreopen} flags,
otherwise libtool will assume that the system does not support dlopening.
The macro must be called @strong{before} @code{AC_PROG_LIBTOOL}.
@end defmac

@defmac 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