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).

