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:
You can follow these examples on your own platform, using the preconfigured libtool script that was installed with libtool (see section 5.3 Configuring libtool).
Source files for the following examples are taken from the `demo' subdirectory of the libtool distribution. Assume that we are building a library, `libhello', out of the files `foo.c' and `hello.c'.
Note that the `foo.c' source file uses the
cos(3) math library
function, which is usually found in the standalone math library, and not
the C library. So, we need to add -lm to the end of
the link line whenever we link `foo.o' or `foo.lo' into an
executable or a library (see section 8 Inter-library dependencies).
The same rule applies whenever you use functions that don't appear in the standard C library... you need to add the appropriate -lname 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 `main.o' against `libhello'.
To create an object file from a source file, the compiler is invoked with the `-c' flag (and any other desired flags):
burger$ gcc -g -O -c main.c burger$
The above compiler command produces an object file, `main.o', from the source 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:
burger$ gcc -g -O -c foo.c burger$ gcc -g -O -c hello.c burger$
Shared libraries, however, may only be built from 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.
Since this is a library implementation detail, libtool hides the complexity of PIC compiler flags by using separate library object files (which end in `.lo' instead of `.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 `foo.c' and `hello.c', simply invoke libtool with the standard compilation command as arguments (see section 4.1 Compile mode):
a23$ libtool gcc -g -O -c foo.c gcc -g -O -c foo.c echo timestamp > foo.lo a23$ libtool gcc -g -O -c hello.c gcc -g -O -c hello.c echo timestamp > hello.lo a23$
Note that libtool creates two files for each invocation. The `.lo' file is a library object, which may be built into a shared library, and the `.o' file is a standard object file. On `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:
burger$ libtool 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$ libtool 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$
Notice that the second run of GCC has its output discarded. This is done so that compiler warnings aren't annoyingly duplicated.
Without libtool, the programmer would invoke the
ar command to
create a static library:
burger$ ar cru libhello.a hello.o foo.o burger$
But of course, that would be too simple, so many systems require that
you run the
ranlib command on the resulting library (to give it
better karma, or something):
burger$ ranlib libhello.a burger$
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
ar (and possibly
Again, the libtool library name differs from the standard name (it has a `.la' suffix instead of a `.a' suffix). The arguments to libtool are the same ones you would use to produce an executable named `libhello.la' with your compiler (see section 4.2 Link mode):
a23$ libtool gcc -g -O -o libhello.la foo.o hello.o libtool: cannot build libtool library `libhello.la' from non-libtool \ objects a23$
Aha! Libtool caught a common error... 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 -lm to the link command line because
`foo.c' uses the
cos(3) math library function (see section 3 Using libtool):
a23$ libtool gcc -g -O -o libhello.la foo.lo hello.lo -lm libtool: you must specify an installation directory with `-rpath' a23$
Argh. Another complication in building shared libraries is that we need
to specify the path to the directory in which they (eventually) will be
installed. So, we try again, with an
rpath setting of
a23$ libtool gcc -g -O -o libhello.la foo.lo hello.lo \ -rpath /usr/local/lib -lm mkdir .libs ar cru .libs/libhello.a foo.o hello.o ranlib .libs/libhello.a creating libhello.la a23$
Now, let's try the same trick on the shared library platform:
burger$ libtool gcc -g -O -o libhello.la foo.lo hello.lo \ -rpath /usr/local/lib -lm mkdir .libs ld -Bshareable -o .libs/libhello.so.0.0 foo.lo hello.lo -lm ar cru .libs/libhello.a foo.o hello.o ranlib .libs/libhello.a creating libhello.la burger$
Now that's significantly cooler... libtool just ran an obscure
ld command to create a shared library, as well as the static
Note how libtool creates extra files in the `.libs' 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.
If you choose at this point to 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 `-L' and `-l' flags to specify the library's location.
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.
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.
Here's the old way of linking against an uninstalled library:
burger$ gcc -g -O -o hell.old main.o libhello.a -lm burger$
Libtool's way is almost the same(1) (see section 4.2 Link mode):
a23$ libtool gcc -g -O -o hell main.o libhello.la -lm gcc -g -O -o hell main.o ./.libs/libhello.a -lm a23$
That looks too simple to be true. All libtool did was transform `libhello.la' to `./.libs/libhello.a', but remember that `a23' has no shared libraries.
On `burger' the situation is different:
burger$ libtool gcc -g -O -o hell main.o libhello.la -lm gcc -g -O -o .libs/hell main.o -L./.libs -R/usr/local/lib -lhello -lm creating hell burger$
Notice that the executable,
hell, was actually created in the
`.libs' subdirectory. Then, a wrapper script was created
in the current directory.
On NetBSD 1.2, libtool encodes the installation directory of `libhello', by using the `-R/usr/local/lib' compiler flag. Then, the wrapper script guarantees that the executable finds the correct shared library (the one in `./.libs') until it is properly installed.
Let's compare the two different programs:
burger$ 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$ 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$
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?
burger$ 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$ ls -l .libs/hell .libs/libhello.* -rwxr-xr-x 1 gord gord 11647 Nov 14 12:10 .libs/hell -rw-r--r-- 1 gord gord 4274 Nov 13 18:44 .libs/libhello.a -rwxr-xr-x 1 gord gord 12205 Nov 13 18:44 .libs/libhello.so.0.0 burger$
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 `libhello' won't be an advantage until we link it against at least a few more programs.
If `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:
burger$ 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) quit burger$
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:
burger$ gdb .libs/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) break main Breakpoint 1 at 0x8048547: file main.c, line 29. (gdb) 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) quit burger$
Argh. Now GDB complains because it cannot find the shared library that `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 `.libs' directory, and just run it on the executable wrapper (see section 4.3 Execute mode):
burger$ libtool 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) break main Breakpoint 1 at 0x8048547: file main.c, line 29. (gdb) 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) quit The program is running. Quit anyway (and kill it)? (y or n) y burger$
Installing libraries on a non-libtool system is quite straightforward... just copy them into place:(2)
burger$ su Password: ******** burger# cp libhello.a /usr/local/lib/libhello.a burger#
Oops, don't forget the
burger# ranlib /usr/local/lib/libhello.a burger#
Libtool installation is quite simple, as well. Just use the
cp command that you normally would
(see section 4.4 Install mode):
a23# libtool cp libhello.la /usr/local/lib/libhello.la cp libhello.la /usr/local/lib/libhello.la cp .libs/libhello.a /usr/local/lib/libhello.a ranlib /usr/local/lib/libhello.a a23#
Note that the libtool library `libhello.la' is also installed, to help libtool with uninstallation (see section 4.6 Uninstall mode) and to help programs with dlopening (see section 9 Dlopened modules).
Here is the shared library example:
burger# libtool install -c libhello.la /usr/local/lib/libhello.la install -c .libs/libhello.so.0.0 /usr/local/lib/libhello.so.0.0 install -c libhello.la /usr/local/lib/libhello.la install -c .libs/libhello.a /usr/local/lib/libhello.a ranlib /usr/local/lib/libhello.a burger#
It is safe to specify the `-s' (strip symbols) flag if you use a BSD-compatible install program when installing libraries. Libtool will either ignore the `-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 `-rpath' flag you used to build it.
Then, running `libtool -n --finish libdir' can give you further hints on what to do (see section 4.5 Finish mode):
burger# libtool -n --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(1) and ld.so(8) manual pages. ---------------------------------------------------------------------- burger#
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.
If you used libtool to link any executables against uninstalled libtool libraries (see section 3.3 Linking executables), you need to use libtool to install the executables after the libraries have been installed (see section 3.5 Installing libraries).
So, for our Ultrix example, we would run:
a23# libtool install -c hell /usr/local/bin/hell install -c hell /usr/local/bin/hell a23#
On shared library systems, libtool just ignores the wrapper script and installs the correct binary:
burger# libtool install -c hell /usr/local/bin/hell install -c .libs/hell /usr/local/bin/hell burger#
Why return to
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 "convenience library" that is a collection of related object
files without a really nice interface.
To do this, you should ignore libtool entirely, and just use the old
ranlib commands to create a static library.
If you want to install the library (but you probably don't), then you may use libtool:
burger$ libtool ./install-sh -c libhello.a /local/lib/libhello.a ./install-sh -c libhello.a /local/lib/libhello.a ranlib /local/lib/libhello.a burger$
Using libtool for static library installation protects your library from
being accidentally stripped (if the installer used the `-s' flag),
as well as automatically running the correct
Another common situation where static linking is desirable is in creating a standalone binary. Use libtool to do the linking and add the `-all-static' flag.
Go to the first, previous, next, last section, table of contents.