libtool.texi

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

Now assume @file{libhello.la} had already been installed, and you want
to link a new program with it.  You could figure out where it lives by
yourself, then run:

@example
burger$ @kbd{gcc -g -O -o test test.o -L/usr/local/lib -lhello}
@end example

However, unless @file{/usr/local/lib} is in the standard library search
path, you won't be able to run @code{test}.  However, if you use libtool
to link the already-installed libtool library, it will do The Right
Thing (TM) for you:

@example
burger$ @kbd{libtool --mode=link gcc -g -O -o test \
                test.o /usr/local/lib/libhello.la}
gcc -g -O -o @value{objdir}/test test.o -Wl,--rpath
-Wl,/usr/local/lib /usr/local/lib/libhello.a -lm
creating test
burger$
@end example

Note that libtool added the necessary run-time path flag, as well as
@samp{-lm}, the library libhello.la depended upon.  Nice, huh?

Since libtool created a wrapper script, you should use libtool to
install it and debug it too.  However, since the program does not depend
on any uninstalled libtool library, it is probably usable even without
the wrapper script.  Libtool could probably be made smarter to avoid the
creation of the wrapper script in this case, but this is left as an
exercise for the reader.


@cindex wrapper scripts for programs
@cindex program wrapper scripts
Notice that the executable, @code{hell}, was actually created in the
@file{@value{objdir}} subdirectory.  Then, a wrapper script was created
in the current directory.

On NetBSD 1.2, libtool encodes the installation directory of
@file{libhello}, by using the @samp{-R/usr/local/lib} compiler flag.
Then, the wrapper script guarantees that the executable finds the
correct shared library (the one in @file{./@value{objdir}}) until it is
properly installed.

Let's compare the two different programs:

@example
burger$ @kbd{time ./hell.old}
Welcome to GNU Hell!
** This is not GNU Hello.  There is no built-in mail reader. **
        0.21 real         0.02 user         0.08 sys
burger$ @kbd{time ./hell}
Welcome to GNU Hell!
** This is not GNU Hello.  There is no built-in mail reader. **
        0.63 real         0.09 user         0.59 sys
burger$
@end example

The wrapper script takes significantly longer to execute, but at least
the results are correct, even though the shared library hasn't been
installed yet.

So, what about all the space savings that shared libraries are supposed
to yield?

@example
burger$ @kbd{ls -l hell.old libhello.a}
-rwxr-xr-x  1 gord  gord  15481 Nov 14 12:11 hell.old
-rw-r--r--  1 gord  gord   4274 Nov 13 18:02 libhello.a
burger$ @kbd{ls -l @value{objdir}/hell @value{objdir}/libhello.*}
-rwxr-xr-x  1 gord  gord  11647 Nov 14 12:10 @value{objdir}/hell
-rw-r--r--  1 gord  gord   4274 Nov 13 18:44 @value{objdir}/libhello.a
-rwxr-xr-x  1 gord  gord  12205 Nov 13 18:44 @value{objdir}/libhello.so.0.0
burger$
@end example

Well, that sucks.  Maybe I should just scrap this project and take up
basket weaving.

Actually, it just proves an important point: shared libraries incur
overhead because of their (relative) complexity.  In this situation, the
price of being dynamic is eight kilobytes, and the payoff is about four
kilobytes.  So, having a shared @file{libhello} won't be an advantage
until we link it against at least a few more programs.

@node Debugging executables
@section Debugging executables

If @file{hell} was a complicated program, you would certainly want to
test and debug it before installing it on your system.  In the above
section, you saw how the libtool wrapper script makes it possible to run
the program directly, but unfortunately, this mechanism interferes with
the debugger:

@example
burger$ @kbd{gdb hell}
GDB is free software and you are welcome to distribute copies of it
 under certain conditions; type "show copying" to see the conditions.
There is no warranty for GDB; type "show warranty" for details.
GDB 4.16 (i386-unknown-netbsd), (C) 1996 Free Software Foundation, Inc.

"hell": not in executable format: File format not recognized

(gdb) @kbd{quit}
burger$
@end example

Sad.  It doesn't work because GDB doesn't know where the executable
lives.  So, let's try again, by invoking GDB directly on the executable:

@example
burger$ @kbd{gdb @value{objdir}/hell}
trick:/home/src/libtool/demo$ gdb .libs/hell
GDB is free software and you are welcome to distribute copies of it
 under certain conditions; type "show copying" to see the conditions.
There is no warranty for GDB; type "show warranty" for details.
GDB 4.16 (i386-unknown-netbsd), (C) 1996 Free Software Foundation, Inc.
(gdb) @kbd{break main}
Breakpoint 1 at 0x8048547: file main.c, line 29.
(gdb) @kbd{run}
Starting program: /home/src/libtool/demo/.libs/hell
/home/src/libtool/demo/.libs/hell: can't load library 'libhello.so.2'

Program exited with code 020.
(gdb) @kbd{quit}
burger$
@end example

Argh.  Now GDB complains because it cannot find the shared library that
@file{hell} is linked against.  So, we must use libtool in order to
properly set the library path and run the debugger.  Fortunately, we can
forget all about the @file{@value{objdir}} directory, and just run it on
the executable wrapper (@pxref{Execute mode}):

@example
burger$ @kbd{libtool --mode=execute gdb hell}
GDB is free software and you are welcome to distribute copies of it
 under certain conditions; type "show copying" to see the conditions.
There is no warranty for GDB; type "show warranty" for details.
GDB 4.16 (i386-unknown-netbsd), (C) 1996 Free Software Foundation, Inc.
(gdb) @kbd{break main}
Breakpoint 1 at 0x8048547: file main.c, line 29.
(gdb) @kbd{run}
Starting program: /home/src/libtool/demo/.libs/hell

Breakpoint 1, main (argc=1, argv=0xbffffc40) at main.c:29
29	  printf ("Welcome to GNU Hell!\n");
(gdb) @kbd{quit}
The program is running.  Quit anyway (and kill it)? (y or n) @kbd{y}
burger$
@end example

@node Installing libraries
@section Installing libraries

@pindex strip
Installing libraries on a non-libtool system is quite
straightforward@dots{} just copy them into place:@footnote{Don't
accidentally strip the libraries, though, or they will be unusable.}

@pindex su
@example
burger$ @kbd{su}
Password: @kbd{********}
burger# @kbd{cp libhello.a /usr/local/lib/libhello.a}
burger#
@end example

Oops, don't forget the @code{ranlib} command:

@example
burger# @kbd{ranlib /usr/local/lib/libhello.a}
burger#
@end example

@pindex install
Libtool installation is quite simple, as well.  Just use the
@code{install} or @code{cp} command that you normally would
(@pxref{Install mode}):

@example
a23# @kbd{libtool --mode=install cp libhello.la /usr/local/lib/libhello.la}
cp libhello.la /usr/local/lib/libhello.la
cp @value{objdir}/libhello.a /usr/local/lib/libhello.a
ranlib /usr/local/lib/libhello.a
a23#
@end example

Note that the libtool library @file{libhello.la} is also installed, to
help libtool with uninstallation (@pxref{Uninstall mode}) and linking
(@pxref{Linking executables}) and to help programs with dlopening
(@pxref{Dlopened modules}).

Here is the shared library example:

@example
burger# @kbd{libtool --mode=install install -c libhello.la \
                /usr/local/lib/libhello.la}
install -c @value{objdir}/libhello.so.0.0 /usr/local/lib/libhello.so.0.0
install -c libhello.la /usr/local/lib/libhello.la
install -c @value{objdir}/libhello.a /usr/local/lib/libhello.a
ranlib /usr/local/lib/libhello.a
burger#
@end example

@cindex stripping libraries
@cindex libraries, stripping
It is safe to specify the @samp{-s} (strip symbols) flag if you use a
BSD-compatible install program when installing libraries.
Libtool will either ignore the @samp{-s} flag, or will run a program
that will strip only debugging and compiler symbols from the library.

Once the libraries have been put in place, there may be some additional
configuration that you need to do before using them.  First, you must
make sure that where the library is installed actually agrees with the
@samp{-rpath} flag you used to build it.

@cindex postinstallation
@cindex installation, finishing
@cindex libraries, finishing installation
Then, running @samp{libtool -n --mode=finish @var{libdir}} can give you
further hints on what to do (@pxref{Finish mode}):

@example
burger# @kbd{libtool -n --mode=finish /usr/local/lib}
PATH="$PATH:/sbin" ldconfig -m /usr/local/lib
-----------------------------------------------------------------
Libraries have been installed in:
   /usr/local/lib

To link against installed libraries in a given directory, LIBDIR,
you must use the `-LLIBDIR' flag during linking.

 You will also need to do one of the following:
   - add LIBDIR to the `LD_LIBRARY_PATH' environment variable
     during execution
   - add LIBDIR to the `LD_RUN_PATH' environment variable
     during linking
   - use the `-RLIBDIR' linker flag

See any operating system documentation about shared libraries for
more information, such as the ld and ld.so manual pages.
-----------------------------------------------------------------
burger#
@end example

After you have completed these steps, you can go on to begin using the
installed libraries.  You may also install any executables that depend
on libraries you created.

@node Installing executables
@section Installing executables

If you used libtool to link any executables against uninstalled libtool
libraries (@pxref{Linking executables}), you need to use libtool to
install the executables after the libraries have been installed
(@pxref{Installing libraries}).

So, for our Ultrix example, we would run:

@example
a23# libtool install -c hell /usr/local/bin/hell
install -c hell /usr/local/bin/hell
a23#
@end example

On shared library systems, libtool just ignores the wrapper script and
installs the correct binary:

@example
burger# libtool install -c hell /usr/local/bin/hell
install -c @value{objdir}/hell /usr/local/bin/hell
burger#
@end example

@node Static libraries
@section Linking static libraries

@cindex static linking
@cindex convenience libraries
Why return to @code{ar} and @code{ranlib} silliness when you've had a
taste of libtool?  Well, sometimes it is desirable to create a static
archive that can never be shared.  The most frequent case is when you
have a set of object files that you use to build several different
programs.  You can create a ``convenience library'' out of those
objects, and link programs with the library, instead of listing all
object files for every program.  This technique is often used to
overcome GNU automake's lack of support for linking object files built
from sources in other directories, because it supports linking with
libraries from other directories.  This limitation applies to GNU
automake up to release 1.4; newer releases should support sources in
other directories.

If you just want to link this convenience library into programs, then
you could just ignore libtool entirely, and use the old @code{ar} and
@code{ranlib} commands (or the corresponding GNU automake
@samp{_LIBRARIES} rules).  You can even install a convenience library
(but you probably don't want to) using libtool:

@example
burger$ @kbd{libtool --mode=install ./install-sh -c libhello.a \
                /local/lib/libhello.a}
./install-sh -c libhello.a /local/lib/libhello.a
ranlib /local/lib/libhello.a
burger$
@end example

Using libtool for static library installation protects your library from
being accidentally stripped (if the installer used the @samp{-s} flag),
as well as automatically running the correct @code{ranlib} command.

But libtool libraries are more than just collections of object files:
they can also carry library dependency information, which old archives
do not.  If you want to create a libtool static convenience library, you
can omit the @samp{-rpath} flag and use @samp{-static} to indicate that
you're only interested in a static library.  When you link a program
with such a library, libtool will actually link all object files and
dependency libraries into the program.

If you omit both @samp{-rpath} and @samp{-static}, libtool will create a
convenience library that can be used to create other libtool
libraries, even shared ones.  Just like in the static case, the library
behaves as an alias to a set of object files and dependency libraries,
but in this case the object files are suitable for inclusion in shared
libraries.  But be careful not to link a single convenience library,
directly or indirectly, into a single program or library, otherwise you
may get errors about symbol redefinitions.

When GNU automake is used, you should use @code{noinst_LTLIBRARIES}
instead of @code{lib_LTLIBRARIES} for convenience libraries, so that
the @samp{-rpath} option is not passed when they are linked.

As a rule of thumb, link a libtool convenience library into at most one
libtool library, and never into a program, and link libtool static
convenience libraries only into programs, and only if you need to carry
library dependency information to the user of the static convenience
library.

@cindex standalone binaries
Another common situation where static linking is desirable is in
creating a standalone binary.  Use libtool to do the linking and add the
@samp{-all-static} flag.