libtool.texi

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

@node Postmortem
@section A postmortem analysis of other implementations

@cindex other implementations, flaws in
@cindex reusability of library systems
In all fairness, each of the implementations that were examined do the
job that they were intended to do, for a number of different host
systems.  However, none of these solutions seem to function well as a
generalized, reusable component.

@cindex complexity of library systems
Most were too complex to use (much less modify) without understanding
exactly what the implementation does, and they were generally not
documented.

The main difficulty is that different vendors have different views of
what libraries are, and none of the packages which were examined seemed
to be confident enough to settle on a single paradigm that just
@emph{works}.

Ideally, libtool would be a standard that would be implemented as series
of extensions and modifications to existing library systems to make them
work consistently.  However, it is not an easy task to convince
operating system developers to mend their evil ways, and people want to
build shared libraries right now, even on buggy, broken, confused
operating systems.

For this reason, libtool was designed as an independent shell script.
It isolates the problems and inconsistencies in library building that
plague @file{Makefile} writers by wrapping the compiler suite on
different platforms with a consistent, powerful interface.

With luck, libtool will be useful to and used by the GNU community, and
that the lessons that were learned in writing it will be taken up by
designers of future library systems.

@node Libtool paradigm
@chapter The libtool paradigm

At first, libtool was designed to support an arbitrary number of library
object types.  After libtool was ported to more platforms, a new
paradigm gradually developed for describing the relationship between
libraries and programs.

@cindex definition of libraries
@cindex libraries, definition of
In summary, ``libraries are programs with multiple entry points, and
more formally defined interfaces.''

Version 0.7 of libtool was a complete redesign and rewrite of libtool to
reflect this new paradigm.  So far, it has proved to be successful:
libtool is simpler and more useful than before.

The best way to introduce the libtool paradigm is to contrast it with
the paradigm of existing library systems, with examples from each.  It
is a new way of thinking, so it may take a little time to absorb, but
when you understand it, the world becomes simpler.

@node Using libtool
@chapter Using libtool

@cindex examples of using libtool
@cindex libtool examples
It makes little sense to talk about using libtool in your own packages
until you have seen how it makes your life simpler.  The examples in
this chapter introduce the main features of libtool by comparing the
standard library building procedure to libtool's operation on two
different platforms:

@table @samp
@item a23
An Ultrix 4.2 platform with only static libraries.

@item burger
A NetBSD/i386 1.2 platform with shared libraries.
@end table

You can follow these examples on your own platform, using the
preconfigured libtool script that was installed with libtool
(@pxref{Configuring}).

Source files for the following examples are taken from the @file{demo}
subdirectory of the libtool distribution.  Assume that we are building a
library, @file{libhello}, out of the files @file{foo.c} and
@file{hello.c}.

Note that the @file{foo.c} source file uses the @code{cos} math library
function, which is usually found in the standalone math library, and not
the C library (@pxref{Trig Functions, , Trigonometric Functions, libc,
The GNU C Library Reference Manual}).  So, we need to add @kbd{-lm} to
the end of the link line whenever we link @file{foo.o} or @file{foo.lo}
into an executable or a library (@pxref{Inter-library dependencies}).

The same rule applies whenever you use functions that don't appear in
the standard C library@dots{} you need to add the appropriate
@kbd{-l@var{name}} flag to the end of the link line when you link
against those objects.

After we have built that library, we want to create a program by linking
@file{main.o} against @file{libhello}.

@menu
* Creating object files::       Compiling object files for libraries.
* Linking libraries::           Creating libraries from object files.
* Linking executables::         Linking object files against libtool libraries.
* Debugging executables::       Running GDB on libtool-generated programs.
* Installing libraries::        Making libraries available to users.
* Installing executables::      Making programs available to users.
* Static libraries::            When shared libraries are not wanted.
@end menu

@node Creating object files
@section Creating object files

@cindex compiling object files
@cindex object files, compiling
To create an object file from a source file, the compiler is invoked
with the `-c' flag (and any other desired flags):

@example
burger$ @kbd{gcc -g -O -c main.c}
burger$
@end example

The above compiler command produces an object file, @file{main.o}, from
the source file @file{main.c}.

For most library systems, creating object files that become part of a
static library is as simple as creating object files that are linked to
form an executable:

@example
burger$ @kbd{gcc -g -O -c foo.c}
burger$ @kbd{gcc -g -O -c hello.c}
burger$
@end example

@cindex position-independent code
@cindex PIC (position-independent code)
Shared libraries, however, may only be built from
@dfn{position-independent code} (PIC).  So, special flags must be passed
to the compiler to tell it to generate PIC rather than the standard
position-dependent code.

@cindex library object file
@cindex @samp{.lo} files
@cindex object files, library
Since this is a library implementation detail, libtool hides the
complexity of PIC compiler flags by using separate library object files
(which end in @samp{.lo} instead of @samp{.o}).  On systems without shared
libraries (or without special PIC compiler flags), these library object
files are identical to ``standard'' object files.

To create library object files for @file{foo.c} and @file{hello.c},
simply invoke libtool with the standard compilation command as
arguments (@pxref{Compile mode}):

@example
a23$ @kbd{libtool --mode=compile gcc -g -O -c foo.c}
gcc -g -O -c foo.c
echo timestamp > foo.lo
a23$ @kbd{libtool --mode=compile gcc -g -O -c hello.c}
gcc -g -O -c hello.c
echo timestamp > hello.lo
a23$
@end example

Note that libtool creates two files for each invocation.  The @samp{.lo}
file is a library object, which may be built into a shared library, and
the @samp{.o} file is a standard object file.  On @samp{a23}, the
library objects are just timestamps, because only static libraries are
supported.

On shared library systems, libtool automatically inserts the PIC
generation flags into the compilation command, so that the library
object and the standard object differ:

@example
burger$ @kbd{libtool --mode=compile gcc -g -O -c foo.c}
gcc -g -O -c -fPIC -DPIC foo.c
mv -f foo.o foo.lo
gcc -g -O -c foo.c >/dev/null 2>&1
burger$ @kbd{libtool --mode=compile gcc -g -O -c hello.c}
gcc -g -O -c -fPIC -DPIC hello.c
mv -f hello.o hello.lo
gcc -g -O -c hello.c >/dev/null 2>&1
burger$
@end example

Notice that the second run of GCC has its output discarded.  This is
done so that compiler warnings aren't annoyingly duplicated.

@node Linking libraries
@section Linking libraries

@pindex ar
Without libtool, the programmer would invoke the @code{ar} command to
create a static library:

@example
burger$ @kbd{ar cru libhello.a hello.o foo.o}
burger$
@end example

@pindex ranlib
But of course, that would be too simple, so many systems require that
you run the @code{ranlib} command on the resulting library (to give it
better karma, or something):

@example
burger$ @kbd{ranlib libhello.a}
burger$
@end example

It seems more natural to use the C compiler for this task, given
libtool's ``libraries are programs'' approach.  So, on platforms without
shared libraries, libtool simply acts as a wrapper for the system
@code{ar} (and possibly @code{ranlib}) commands.

@cindex libtool libraries
@cindex @samp{.la} files
Again, the libtool library name differs from the standard name (it has a
@samp{.la} suffix instead of a @samp{.a} suffix).  The arguments to libtool are
the same ones you would use to produce an executable named
@file{libhello.la} with your compiler (@pxref{Link mode}):

@example
a23$ @kbd{libtool --mode=link gcc -g -O -o libhello.la foo.o hello.o}
libtool: cannot build libtool library `libhello.la' from non-libtool \
                objects
a23$
@end example

Aha!  Libtool caught a common error@dots{} trying to build a library
from standard objects instead of library objects.  This doesn't matter
for static libraries, but on shared library systems, it is of great
importance.

So, let's try again, this time with the library object files.  Remember
also that we need to add @kbd{-lm} to the link command line because
@file{foo.c} uses the @code{cos} math library function (@pxref{Using
libtool}).

Another complication in building shared libraries is that we need to
specify the path to the directory in which they (eventually) will be
installed (in this case, @file{/usr/local/lib})@footnote{If you don't
specify an @code{rpath}, then libtool builds a libtool convenience
archive, not a shared library (@pxref{Static libraries}).}:

@example
a23$ @kbd{libtool --mode=link gcc -g -O -o libhello.la foo.lo hello.lo \
                -rpath /usr/local/lib -lm}
mkdir @value{objdir}
ar cru @value{objdir}/libhello.a foo.o hello.o
ranlib @value{objdir}/libhello.a
creating libhello.la
a23$
@end example

Now, let's try the same trick on the shared library platform:

@example
burger$ @kbd{libtool --mode=link gcc -g -O -o libhello.la foo.lo hello.lo \
                -rpath /usr/local/lib -lm}
mkdir @value{objdir}
ld -Bshareable -o @value{objdir}/libhello.so.0.0 foo.lo hello.lo -lm
ar cru @value{objdir}/libhello.a foo.o hello.o
ranlib @value{objdir}/libhello.a
creating libhello.la
burger$
@end example

Now that's significantly cooler@dots{} libtool just ran an obscure
@code{ld} command to create a shared library, as well as the static
library.

@cindex @file{@value{objdir}} subdirectory
Note how libtool creates extra files in the @file{@value{objdir}}
subdirectory, rather than the current directory.  This feature is to
make it easier to clean up the build directory, and to help ensure that
other programs fail horribly if you accidentally forget to use libtool
when you should.

@node Linking executables
@section Linking executables

@cindex linking against installed libraries
If you choose at this point to @dfn{install} the library (put it in a
permanent location) before linking executables against it, then you
don't need to use libtool to do the linking.  Simply use the appropriate
@samp{-L} and @samp{-l} flags to specify the library's location.

@cindex buggy system linkers
Some system linkers insist on encoding the full directory name of each
shared library in the resulting executable.  Libtool has to work around
this misfeature by special magic to ensure that only permanent directory
names are put into installed executables.

@cindex security problems with buggy linkers
@cindex bugs, subtle ones caused by buggy linkers
The importance of this bug must not be overlooked: it won't cause
programs to crash in obvious ways.  It creates a security hole,
and possibly even worse, if you are modifying the library source code
after you have installed the package, you will change the behaviour of
the installed programs!

So, if you want to link programs against the library before you install
it, you must use libtool to do the linking.

@cindex linking against uninstalled libraries
Here's the old way of linking against an uninstalled library:

@example
burger$ @kbd{gcc -g -O -o hell.old main.o libhello.a -lm}
burger$
@end example

Libtool's way is almost the same@footnote{However, you should avoid using
@samp{-L} or @samp{-l} flags to link against an uninstalled libtool
library.  Just specify the relative path to the @samp{.la} file, such as
@file{../intl/libintl.la}.  This is a design decision to eliminate any
ambiguity when linking against uninstalled shared libraries.}
(@pxref{Link mode}):

@example
a23$ @kbd{libtool --mode=link gcc -g -O -o hell main.o libhello.la -lm}
gcc -g -O -o hell main.o ./@value{objdir}/libhello.a -lm
a23$
@end example

That looks too simple to be true.  All libtool did was transform
@file{libhello.la} to @file{./@value{objdir}/libhello.a}, but remember
that @samp{a23} has no shared libraries.

On @samp{burger} the situation is different:

@example
burger$ @kbd{libtool --mode=link gcc -g -O -o hell main.o libhello.la -lm}
gcc -g -O -o @value{objdir}/hell main.o -L./@value{objdir} -R/usr/local/lib -lhello -lm
creating hell
burger$
@end example

@cindex linking with installed libtool libraries