This is libtool.info, produced by makeinfo version 3.12k from
libtool.texi.
INFO-DIR-SECTION GNU programming tools
START-INFO-DIR-ENTRY
* Libtool: (libtool). Generic shared library support script.
END-INFO-DIR-ENTRY
INFO-DIR-SECTION Individual utilities
START-INFO-DIR-ENTRY
* libtoolize: (libtool)Invoking libtoolize. Adding libtool support.
END-INFO-DIR-ENTRY
This file documents GNU Libtool 1.3.5
Copyright (C) 1996-1999 Free Software Foundation, Inc.
Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.
Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided that the
entire resulting derived work is distributed under the terms of a
permission notice identical to this one.
Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that this permission notice may be stated in a
translation approved by the Foundation.
File: libtool.info, Node: Top, Next: Introduction, Prev: (dir), Up: (dir)
Shared library support for GNU
******************************
This file documents GNU Libtool, a script that allows package
developers to provide generic shared library support. This edition
documents version 1.3.5.
*Note Reporting bugs::, for information on how to report problems
with libtool.
* Menu:
* Introduction:: What the heck is libtool?
* Libtool paradigm:: How libtool's view of libraries is different.
* Using libtool:: Example of using libtool to build libraries.
* Invoking libtool:: Running the `libtool' script.
* Integrating libtool:: Using libtool in your own packages.
* Versioning:: Using library interface versions.
* Library tips:: Tips for library interface design.
* Inter-library dependencies:: Libraries that depend on other libraries.
* Dlopened modules:: `dlopen'ing libtool-created libraries.
* Using libltdl:: Libtool's portable `dlopen' wrapper library.
* Other languages:: Using libtool without a C compiler.
* Troubleshooting:: When libtool doesn't work as advertised.
* Maintaining:: Information used by the libtool maintainer.
* Index:: Full index.
Introduction
* Motivation:: Why does GNU need a libtool?
* Issues:: The problems that need to be addressed.
* Other implementations:: How other people have solved these issues.
* Postmortem:: Learning from past difficulties.
Using libtool
* 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.
Invoking `libtool'
* Compile mode:: Creating library object files.
* Link mode:: Generating executables and libraries.
* Execute mode:: Debugging libtool-generated programs.
* Install mode:: Making libraries and executables public.
* Finish mode:: Completing a library installation.
* Uninstall mode:: Removing executables and libraries.
Integrating libtool with your package
* Makefile rules:: Writing `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.
Configuring libtool
* Invoking ltconfig:: `ltconfig' command line options.
* ltconfig example:: Manually configuring a `libtool'.
* AM_PROG_LIBTOOL:: Configuring `libtool' in `configure.in'.
Including libtool in your package
* Invoking libtoolize:: `libtoolize' command line options.
* Autoconf .o macros:: Autoconf macros that set object file names.
Library interface versions
* Interfaces:: What are library interfaces?
* Libtool versioning:: Libtool's versioning system.
* Updating version info:: Changing version information before releases.
* Release numbers:: Breaking binary compatibility for aesthetics.
Tips for interface design
* C header files:: How to write portable include files.
Dlopened modules
* Building modules:: Creating dlopenable objects and libraries.
* Dlpreopening:: Dlopening that works on static platforms.
* Finding the dlname:: Choosing the right file to `dlopen'.
* Dlopen issues:: Unresolved problems that need your attention.
Using libltdl
* Libltdl interface:: How to use libltdl in your programs.
* Modules for libltdl:: Creating modules that can be `dlopen'ed.
* Distributing libltdl:: How to distribute libltdl with your package.
Using libtool with other languages
* C++ libraries::
Troubleshooting
* Libtool test suite:: Libtool's self-tests.
* Reporting bugs:: How to report problems with libtool.
The libtool test suite
* Test descriptions:: The contents of the test suite.
* When tests fail:: What to do when a test fails.
Maintenance notes for libtool
* New ports:: How to port libtool to new systems.
* Tested platforms:: When libtool was last tested.
* Platform quirks:: Information about different library systems.
* libtool script contents:: Configuration information that libtool uses.
* Cheap tricks:: Making libtool maintainership easier.
Porting libtool to new systems
* Information sources:: Where to find relevant documentation
* Porting inter-library dependencies:: Implementation details explained
Platform quirks
* References:: Finding more information.
* Compilers:: Creating object files from source files.
* Reloadable objects:: Binding object files together.
* Archivers:: Programs that create static archives.
File: libtool.info, Node: Introduction, Next: Libtool paradigm, Prev: Top, Up: Top
Introduction
************
In the past, if a source code package developer wanted to take
advantage of the power of shared libraries, he needed to write custom
support code for each platform on which his package ran. He also had
to design a configuration interface so that the package installer could
choose what sort of libraries were built.
GNU Libtool simplifies the developer's job by encapsulating both the
platform-specific dependencies, and the user interface, in a single
script. GNU Libtool is designed so that the complete functionality of
each host type is available via a generic interface, but nasty quirks
are hidden from the programmer.
GNU Libtool's consistent interface is reassuring... users don't need
to read obscure documentation in order to have their favorite source
package build shared libraries. They just run your package `configure'
script (or equivalent), and libtool does all the dirty work.
There are several examples throughout this document. All assume the
same environment: we want to build a library, `libhello', in a generic
way.
`libhello' could be a shared library, a static library, or both...
whatever is available on the host system, as long as libtool has been
ported to it.
This chapter explains the original design philosophy of libtool.
Feel free to skip to the next chapter, unless you are interested in
history, or want to write code to extend libtool in a consistent way.
* Menu:
* Motivation:: Why does GNU need a libtool?
* Issues:: The problems that need to be addressed.
* Other implementations:: How other people have solved these issues.
* Postmortem:: Learning from past difficulties.
File: libtool.info, Node: Motivation, Next: Issues, Up: Introduction
Motivation for writing libtool
==============================
Since early 1995, several different GNU developers have recognized
the importance of having shared library support for their packages. The
primary motivation for such a change is to encourage modularity and
reuse of code (both conceptually and physically) in GNU programs.
Such a demand means that the way libraries are built in GNU packages
needs to be general, to allow for any library type the package installer
might want. The problem is compounded by the absence of a standard
procedure for creating shared libraries on different platforms.
The following sections outline the major issues facing shared library
support in GNU, and how shared library support could be standardized
with libtool.
The following specifications were used in developing and evaluating
this system:
1. The system must be as elegant as possible.
2. The system must be fully integrated with the GNU Autoconf and
Automake utilities, so that it will be easy for GNU maintainers to
use. However, the system must not require these tools, so that it
can be used by non-GNU packages.
3. Portability to other (non-GNU) architectures and tools is
desirable.
File: libtool.info, Node: Issues, Next: Other implementations, Prev: Motivation, Up: Introduction
Implementation issues
=====================
The following issues need to be addressed in any reusable shared
library system, specifically libtool:
1. The package installer should be able to control what sort of
libraries are built.
2. It can be tricky to run dynamically linked programs whose
libraries have not yet been installed. `LD_LIBRARY_PATH' must be
set properly (if it is supported), or programs fail to run.
3. The system must operate consistently even on hosts which don't
support shared libraries.
4. The commands required to build shared libraries may differ wildly
from host to host. These need to be determined at configure time
in a consistent way.
5. It is not always obvious with which suffix a shared library should
be installed. This makes it difficult for `Makefile' rules, since
they generally assume that file names are the same from host to
host.
6. The system needs a simple library version number abstraction, so
that shared libraries can be upgraded in place. The programmer
should be informed how to design the interfaces to the library to
maximize binary compatibility.
7. The install `Makefile' target should warn the package installer to
set the proper environment variables (`LD_LIBRARY_PATH' or
equivalent), or run `ldconfig'.
File: libtool.info, Node: Other implementations, Next: Postmortem, Prev: Issues, Up: Introduction
Other implementations
=====================
Even before libtool was developed, many free software packages built
and installed their own shared libraries. At first, these packages were
examined to avoid reinventing existing features.
Now it is clear that none of these packages have documented the
details of shared library systems that libtool requires. So, other
packages have been more or less abandoned as influences.
File: libtool.info, Node: Postmortem, Prev: Other implementations, Up: Introduction
A postmortem analysis of other implementations
==============================================
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.
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 _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 `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.
File: libtool.info, Node: Libtool paradigm, Next: Using libtool, Prev: Introduction, Up: Top
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.
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.
File: libtool.info, Node: Using libtool, Next: Invoking libtool, Prev: Libtool paradigm, Up: Top
Using libtool
*************
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:
`a23'
An Ultrix 4.2 platform with only static libraries.
`burger'
A NetBSD/i386 1.2 platform with shared libraries.
You can follow these examples on your own platform, using the
preconfigured libtool script that was installed with libtool (*note
Configuring::).
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' math library
function, which is usually found in the standalone math library, and not
the C library (*note Trigonometric Functions: (libc)Trig Functions).
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 (*note
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'.
* 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.
File: libtool.info, Node: Creating object files, Next: Linking libraries, Up: Using libtool
Creating object files
=====================
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
(*note 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.
File: libtool.info, Node: Linking libraries, Next: Linking executables, Prev: Creating object files, Up: Using libtool
Linking libraries
=================
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 `ranlib') commands.
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 (*note 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' math library function (*note 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, `/usr/local/lib')(1):
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 library.
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.
---------- Footnotes ----------
(1) If you don't specify an `rpath', then libtool builds a libtool
convenience archive, not a shared library (*note Static libraries::).
File: libtool.info, Node: Linking executables, Next: Debugging executables, Prev: Linking libraries, Up: Using libtool
Linking executables
===================
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) (*note 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$
Now assume `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:
burger$ gcc -g -O -o test test.o -L/usr/local/lib -lhello
However, unless `/usr/local/lib' is in the standard library search
path, you won't be able to run `test'. However, if you use libtool to
link the already-installed libtool library, it will do The Right Thing
(TM) for you:
burger$ libtool gcc -g -O -o test test.o /usr/local/lib/libhello.la
gcc -g -O -o .libs/test test.o -Wl,--rpath
-Wl,/usr/local/lib /usr/local/lib/libhello.a -lm
creating test
burger$
Note that libtool added the necessary run-time path flag, as well as
`-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.
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.
---------- Footnotes ----------
(1) However, you should avoid using `-L' or `-l' flags to link
against an uninstalled libtool library. Just specify the relative path
to the `.la' file, such as `../intl/libintl.la'. This is a design
decision to eliminate any ambiguity when linking against uninstalled
shared libraries.
File: libtool.info, Node: Debugging executables, Next: Installing libraries, Prev: Linking executables, Up: Using libtool
Debugging executables
=====================
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 (*note 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$
File: libtool.info, Node: Installing libraries, Next: Installing executables, Prev: Debugging executables, Up: Using libtool
Installing libraries
====================
Installing libraries on a non-libtool system is quite
straightforward... just copy them into place:(1)
burger$ su
Password: ********
burger# cp libhello.a /usr/local/lib/libhello.a
burger#
Oops, don't forget the `ranlib' command:
burger# ranlib /usr/local/lib/libhello.a
burger#
Libtool installation is quite simple, as well. Just use the
`install' or `cp' command that you normally would (*note 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 (*note Uninstall mode::) and linking
(*note Linking executables::) and to help programs with dlopening
(*note 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 (*note 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 and ld.so 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.
---------- Footnotes ----------
(1) Don't accidentally strip the libraries, though, or they will be
unusable.
File: libtool.info, Node: Installing executables, Next: Static libraries, Prev: Installing libraries, Up: Using libtool
Installing executables
======================
If you used libtool to link any executables against uninstalled
libtool libraries (*note Linking executables::), you need to use
libtool to install the executables after the libraries have been
installed (*note 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#
File: libtool.info, Node: Static libraries, Prev: Installing executables, Up: Using libtool
Linking static libraries
========================
Why return to `ar' and `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 `ar' and
`ranlib' commands (or the corresponding GNU automake `_LIBRARIES'
rules). You can even install a convenience library (but you probably
don't want to) using 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 `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 `-rpath' flag and use `-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 `-rpath' and `-static', libtool create a libtool
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 `noinst_LTLIBRARIES'
instead of `lib_LTLIBRARIES' for convenience libraries, so that
the
`-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.
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.
File: libtool.info, Node: Invoking libtool, Next: Integrating libtool, Prev: Using libtool, Up: Top
Invoking `libtool'
******************
The `libtool' program has the following synopsis:
libtool [OPTION]... [MODE-ARG]...
and accepts the following options:
`--config'
Display libtool configuration variables and exit.
`--debug'
Dump a trace of shell script execution to standard output. This
produces a lot of output, so you may wish to pipe it to `less' (or
`more') or redirect to a file.
`-n'
`--dry-run'
Don't create, modify, or delete any files, just show what commands
would be executed by libtool.
`--features'
Display basic configuration options. This provides a way for
packages to determine whether shared or static libraries will be
built.
`--finish'
Same as `--mode=finish'.
`--help'
Display a help message and exit. If `--mode=MODE' is specified,
then detailed help for MODE is displayed.
`--mode=MODE'
Use MODE as the operation mode. By default, the operation mode is
inferred from the MODE-ARGS.
If MODE is specified, it must be one of the following:
`compile'
Compile a source file into a libtool object.
`execute'
Automatically set the library path so that another program
can use uninstalled libtool-generated programs or libraries.
`finish'
Complete the installation of libtool libraries on the system.
`install'
Install libraries or executables.
`link'
Create a library or an executable.
`uninstall'
Delete libraries or executables.
`--version'
Print libtool version information and exit.
The MODE-ARGS are a variable number of arguments, depending on the
selected operation mode. In general, each MODE-ARG is interpreted by
programs libtool invokes, rather than libtool itself.
* Menu:
* Compile mode:: Creating library object files.
* Link mode:: Generating executables and libraries.
* Execute mode:: Debugging libtool-generated programs.
* Install mode:: Making libraries and executables public.
* Finish mode:: Completing a library installation.
* Uninstall mode:: Removing executables and libraries.
File: libtool.info, Node: Compile mode, Next: Link mode, Up: Invoking libtool
Compile mode
============
For "compile" mode, MODE-ARGS is a compiler command to be used in
creating a `standard' object file. These arguments should begin with
the name of the C compiler, and contain the `-c' compiler flag so that
only an object file is created.
Libtool determines the name of the output file by removing the
directory component from the source file name, then substituting the
source code suffix (e.g. `.c' for C source code) with the library
object suffix, `.lo'.
If shared libraries are being built, any necessary PIC generation
flags are substituted into the compilation command.
If the `-static' option is given, then a `.o' file is built, even if
libtool was configured with `--disable-static'.
Note that the `-o' option is now fully supported. It is emulated on
the platforms that don't support it (by locking and moving the
objects), so it is really easy to use libtool, just with minor
modifications to your Makefiles. Typing for example
libtool gcc -c foo/x.c -o foo/x.lo
will do what you expect.
Note, however, that, if the compiler does not support `-c' and `-o',
it is impossible to compile `foo/x.c' without overwriting an existing
`./x.o'. Therefore, if you do have a source file `./x.c', make sure
you introduce dependencies in your `Makefile' to make sure `./x.o' (or
`./x.lo') is re-created after any sub-directory's `x.lo':
x.o x.lo: foo/x.lo bar/x.lo
This will also ensure that make won't try to use a temporarily
corrupted `x.o' to create a program or library. It may cause needless
recompilation on platforms that support `-c' and `-o' together, but
it's the only way to make it safe for those that don't.
File: libtool.info, Node: Link mode, Next: Execute mode, Prev: Compile mode, Up: Invoking libtool
Link mode
=========
"Link" mode links together object files (including library objects)
to form another library or to create an executable program.
MODE-ARGS consist of a command using the C compiler to create an
output file (with the `-o' flag) from several object files.
The following components of MODE-ARGS are treated specially:
`-all-static'
If OUTPUT-FILE is a program, then do not link it against any
shared libraries at all. If OUTPUT-FILE is a library, then only
create a static library.
`-avoid-version'
Tries to avoid versioning (*note Versioning::) for libraries and
modules, i.e. no version information is stored and no symbolic
links are created. If the platform requires versioning, this
option has no effect.
`-dlopen FILE'
Same as `-dlpreopen FILE', if native dlopening is not supported on
the host platform (*note Dlopened modules::) or if the program is
linked with `-static' or `-all-static'. Otherwise, no effect. If
FILE is `self' libtool will make sure that the program can
`dlopen' itself, either by enabling `-export-dynamic' or by
falling back to `-dlpreopen self'.
`-dlpreopen FILE'
Link FILE into the output program, and add its symbols to
LT_PRELOADED_SYMBOLS (*note Dlpreopening::). If FILE is `self',
the symbols of the program itself will be added to
LT_PRELOADED_SYMBOLS. If FILE is `force' libtool will make sure
that LT_PRELOADED_SYMBOLS is always _defined_, regardless of
whether it's empty or not.
`-export-dynamic'
Allow symbols from OUTPUT-FILE to be resolved with `dlsym' (*note
Dlopened modules::).
`-export-symbols SYMFILE'
Tells the linker to export only the symbols listed in SYMFILE.
The symbol file should end in `.sym' and must contain the name of
one symbol per line. This option has no effect on some platforms.
By default all symbols are exported.
`-export-symbols-regex REGEX'
Same as `-export-symbols', except that only symbols matching the
regular expression REGEX are exported. By default all symbols are
exported.
`-LLIBDIR'
Search LIBDIR for required libraries that have already been
installed.
`-lNAME'
OUTPUT-FILE requires the installed library `libNAME'. This option
is required even when OUTPUT-FILE is not an executable.
`-module'
Creates a library that can be dlopened (*note Dlopened modules::).
This option doesn't work for programs. Module names don't need to
be prefixed with 'lib'. In order to prevent name clashes,
however, 'libname' and 'name' must not be used at the same time in
your package.
`-no-undefined'
Declare that OUTPUT-FILE does not depend on any other libraries.
Some platforms cannot create shared libraries that depend on other
libraries (*note Inter-library dependencies::).
`-o OUTPUT-FILE'
Create OUTPUT-FILE from the specified objects and libraries.
`-release RELEASE'
Specify that the library was generated by release RELEASE of your
package, so that users can easily tell which versions are newer
than others. Be warned that no two releases of your package will
be binary compatible if you use this flag. If you want binary
compatibility, use the `-version-info' flag instead (*note
Versioning::).
`-rpath LIBDIR'
If OUTPUT-FILE is a library, it will eventually be installed in
LIBDIR. If OUTPUT-FILE is a program, add LIBDIR to the run-time
path of the program.
`-R LIBDIR'
If OUTPUT-FILE is a program, add LIBDIR to its run-time path. If
OUTPUT-FILE is a library, add -RLIBDIR to its DEPENDENCY_LIBS, so
that, whenever the library is linked into a program, LIBDIR will
be added to its run-time path.
`-static'
If OUTPUT-FILE is a program, then do not link it against any
uninstalled shared libtool libraries. If OUTPUT-FILE is a
library, then only create a static library.
`-version-info CURRENT[:REVISION[:AGE]]'
If OUTPUT-FILE is a libtool library, use interface version
information CURRENT, REVISION, and AGE to build it (*note
Versioning::). Do *not* use this flag to specify package release
information, rather see the `-release' flag.
If the OUTPUT-FILE ends in `.la', then a libtool library is created,
which must be built only from library objects (`.lo' files). The
`-rpath' option is required. In the current implementation, libtool
libraries may not depend on other uninstalled libtool libraries (*note
Inter-library dependencies::).
If the OUTPUT-FILE ends in `.a', then a standard library is created
using `ar' and possibly `ranlib'.
If OUTPUT-FILE ends in `.o' or `.lo', then a reloadable object file
is created from the input files (generally using `ld -r'). This method
is often called "partial linking".
Otherwise, an executable program is created.
File: libtool.info, Node: Execute mode, Next: Install mode, Prev: Link mode, Up: Invoking libtool
Execute mode
============
For "execute" mode, the library path is automatically set, then a
program is executed.
The first of the MODE-ARGS is treated as a program name, with the
rest as arguments to that program.
The following components of MODE-ARGS are treated specially:
`-dlopen FILE'
Add the directory containing FILE to the library path.
This mode sets the library path environment variable according to any
`-dlopen' flags.
If any of the 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.
File: libtool.info, Node: Install mode, Next: Finish mode, Prev: Execute mode, Up: Invoking libtool
Install mode
============
In "install" mode, libtool interprets MODE-ARGS as an installation
command beginning with `cp', or a BSD-compatible `install' program.
The rest of the MODE-ARGS are interpreted as arguments to that
command.
The command is run, and any necessary unprivileged post-installation
commands are also completed.
File: libtool.info, Node: Finish mode, Next: Uninstall mode, Prev: Install mode, Up: Invoking libtool
Finish mode
===========
"Finish" mode helps system administrators install libtool libraries
so that they can be located and linked into user programs.
Each MODE-ARG is interpreted as the name of a library directory.
Running this command may require superuser privileges, so the
`--dry-run' option may be useful.
File: libtool.info, Node: Uninstall mode, Prev: Finish mode, Up: Invoking libtool
Uninstall mode
==============
"Uninstall" mode deletes installed libraries, executables and
objects.
The first MODE-ARG is the name of the program to use to delete files
(typically `/bin/rm').
The remaining MODE-ARGS are either flags for the deletion program
(beginning with a `-'), or the names of files to delete.
File: libtool.info, Node: Integrating libtool, Next: Versioning, Prev: Invoking libtool, Up: Top
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 `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.
File: libtool.info, Node: Makefile rules, Next: Using Automake, Up: Integrating libtool
Writing `Makefile' rules for libtool
====================================
Libtool is fully integrated with Automake (*note Introduction:
(automake)Top), starting with Automake version 1.2.
If you want to use libtool in a regular `Makefile' (or
`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:
1. Download Automake (version 1.2 or later) from your nearest GNU
mirror, install it, and start using it.
2. Learn how to write `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 `Makefile.in' in
the `demo' subdirectory of the libtool distribution... note
especially that it was automatically generated from the
`Makefile.am' by Automake).