libtool.texi

这是一个自动生成MAKEFILE的工具。一个很有用的库。在LINUX工程项目里是很好的帮手。希望对大家有点帮助。

@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 that any library data items
are exported with @code{__declspec(dllexport)} and imported with
@code{__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 @strong{before} @code{AC_PROG_LIBTOOL}, and
provision must be made to pass @samp{-no-undefined} to @code{libtool}
in link mode from the package @code{Makefile}.  Naturally, if you pass
@samp{-no-undefined}, you must ensure that all the library symbols
@strong{really are} defined at link time!
@end defmac

@defmac AC_DISABLE_FAST_INSTALL
Change the default behaviour for @code{AC_PROG_LIBTOOL} to disable
optimization for fast installation.  The user may still override this
default, depending on platform support, by specifying
@samp{--enable-fast-install}.
@end defmac

@defmac AC_DISABLE_SHARED
@defmacx AM_DISABLE_SHARED
Change the default behaviour for @code{AC_PROG_LIBTOOL} to disable
shared libraries.  The user may still override this default by
specifying @samp{--enable-shared}.
@end defmac

@defmac AC_DISABLE_STATIC
@defmacx AM_DISABLE_STATIC
Change the default behaviour for @code{AC_PROG_LIBTOOL} to disable
static libraries.  The user may still override this default by
specifying @samp{--enable-static}.
@end defmac

The tests in @code{AC_PROG_LIBTOOL} also recognize the following
environment variables:

@defvar CC
The C compiler that will be used by the generated @code{libtool}.  If
this is not set, @code{AC_PROG_LIBTOOL} will look for @code{gcc} or
@code{cc}.
@end defvar

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

@defvar CPPFLAGS
C preprocessor flags.  If this is not set, @code{AC_PROG_LIBTOOL} will
not use any such flags.  It affects only the way @code{AC_PROG_LIBTOOL}
runs tests, not the produced @code{libtool}.
@end defvar

@defvar LD
The system linker to use (if the generated @code{libtool} requires one).
If this is not set, @code{AC_PROG_LIBTOOL} will try to find out what is
the linker used by @var{CC}.
@end defvar

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

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

@defvar NM
Program to use rather than checking for @code{nm}.
@end defvar

@defvar RANLIB
Program to use rather than checking for @code{ranlib}.
@end defvar

@defvar LN_S
A command that creates a link of a program, a soft-link if possible, a
hard-link otherwise.  @code{AC_PROG_LIBTOOL} will check for a suitable
program if this variable is not set.
@end defvar

@defvar DLLTOOL
Program to use rather than checking for @code{dlltool}.  Only meaningful
for Cygwin/MS-Windows.
@end defvar

@defvar OBJDUMP
Program to use rather than checking for @code{objdump}.  Only meaningful
for Cygwin/MS-Windows.
@end defvar

@defvar AS
Program to use rather than checking for @code{as}.  Only used on
Cygwin/MS-Windows at the moment.
@end defvar

@pindex aclocal
When you invoke the @code{libtoolize} program (@pxref{Invoking
libtoolize}), it will tell you where to find a definition of
@code{AC_PROG_LIBTOOL}.  If you use Automake, the @code{aclocal} program
will automatically add @code{AC_PROG_LIBTOOL} support to your
@code{configure} script.

Nevertheless, it is advisable to include a copy of @file{libtool.m4} in
@file{acinclude.m4}, so that, even if @file{aclocal.m4} and
@file{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 @file{libtool.m4} installed and accessible for
@code{aclocal}.  This may lead to weird errors when versions don't
match.

@node Distributing
@section Including libtool in your package

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

@table @file
@item config.guess
@pindex config.guess
Attempt to guess a canonical system name.

@item config.sub
@pindex config.sub
Canonical system name validation subroutine script.

@item ltmain.sh
@pindex ltmain.sh
A generic script implementing basic libtool functionality.
@end table

Note that the libtool script itself should @emph{not} be included with
your package.  @xref{Configuring}.

You should use the @code{libt