-\input texinfo @c -*-texinfo-*-
-
-@c $Id$
-
-@c %**start of header
-@setfilename libtool.info
-@settitle Libtool
-@c For double-sided printing, uncomment:
-@c @setchapternewpage odd
-@c %**end of header
-
-@include version.texi
-@set BUGADDR the libtool bug reporting address @email{bug-libtool@@gnu.org}
-@set MAILLIST the libtool mailing list @email{libtool@@gnu.org}
-@set objdir .libs
-
-@dircategory GNU programming tools
-@direntry
-* Libtool: (libtool). Generic shared library support script.
-@end direntry
-
-@dircategory Individual utilities
-@direntry
-* libtoolize: (libtool)Invoking libtoolize. Adding libtool support.
-@end direntry
-
-@ifinfo
-This file documents GNU Libtool @value{VERSION}
-
-Copyright (C) 1996-2000 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.
-
-@ignore
-Permission is granted to process this file through TeX and print the
-results, provided the printed document carries copying permission notice
-identical to this one except for the removal of this paragraph
-
-
-@end ignore
-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.
-@end ifinfo
-
-
-@titlepage
-@title GNU Libtool
-@subtitle For version @value{VERSION}, @value{UPDATED}
-@author Gordon Matzigkeit
-@author Alexandre Oliva
-@author Thomas Tanner
-@author Gary V. Vaughan
-
-@page
-@vskip 0pt plus 1filll
-Copyright @copyright{} 1996-2000 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 Free Software Foundation.
-@end titlepage
-
-@c Put everything in one index (arbitrarily chosen to be the concept index).
-@syncodeindex vr cp
-@syncodeindex fn cp
-@syncodeindex tp cp
-@synindex pg cp
-
-@ifinfo
-@node Top, Introduction, (dir), (dir)
-@comment node-name, next, previous, up
-@top 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 @value{VERSION}.
-
-@xref{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 @code{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:: @code{dlopen}ing libtool-created libraries.
-* Using libltdl:: Libtool's portable @code{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.
-
-@detailmenu --- The Detailed Node Listing ---
-
-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 @code{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 installed executables and libraries.
-* Clean mode:: Removing uninstalled executables and libraries.
-
-Integrating libtool with your package
-
-* Makefile rules:: Writing @file{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:: @code{ltconfig} command line options.
-* ltconfig example:: Manually configuring a @code{libtool}.
-* AM_PROG_LIBTOOL:: Configuring @code{libtool} in @file{configure.in}.
-
-Including libtool in your package
-
-* Invoking libtoolize:: @code{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 @code{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 @code{dlopen}ed.
-* Distributing libltdl:: How to distribute libltdl with your package.
-* Module loaders for libltdl:: Creating user defined module loaders.
-
-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.
-
-@end detailmenu
-@end menu
-
-@end ifinfo
-
-@node Introduction
-@chapter 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@dots{} users don't need
-to read obscure documentation in order to have their favorite source
-package build shared libraries. They just run your package
-@code{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, @file{libhello}, in a
-generic way.
-
-@file{libhello} could be a shared library, a static library, or
-both@dots{} 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.
-@end menu
-
-@node Motivation
-@section Motivation for writing libtool
-
-@cindex motivation for writing libtool
-@cindex design philosophy
-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.
-
-@cindex specifications for libtool
-@cindex libtool specifications
-The following specifications were used in developing and evaluating this
-system:
-
-@enumerate
-@item
-The system must be as elegant as possible.
-
-@item
-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.
-
-@item
-Portability to other (non-GNU) architectures and tools is desirable.
-@end enumerate
-
-@node Issues
-@section Implementation issues
-
-@cindex tricky design issues
-@cindex design issues
-The following issues need to be addressed in any reusable shared library
-system, specifically libtool:
-
-@enumerate
-@item
-The package installer should be able to control what sort of libraries
-are built.
-
-@item
-It can be tricky to run dynamically linked programs whose libraries have
-not yet been installed. @code{LD_LIBRARY_PATH} must be set properly (if
-it is supported), or programs fail to run.
-
-@item
-The system must operate consistently even on hosts which don't support
-shared libraries.
-
-@item
-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.
-
-@item
-It is not always obvious with which suffix a shared library should be
-installed. This makes it difficult for @file{Makefile} rules, since they
-generally assume that file names are the same from host to host.
-
-@item
-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.
-
-@item
-The install @file{Makefile} target should warn the package installer to set
-the proper environment variables (@code{LD_LIBRARY_PATH} or equivalent),
-or run @code{ldconfig}.
-@end enumerate
-
-@node Other implementations
-@section 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.
-
-@node Postmortem
-@section A postmortem analysis of other implementations
-
-@cindex other implementations, flaws in
-@cindex reusability of library systems
-In all fairness, each of the implementations that were examined do the
-job that they were intended to do, for a number of different host
-systems. However, none of these solutions seem to function well as a
-generalized, reusable component.
-
-@cindex complexity of library systems
-Most were too complex to use (much less modify) without understanding
-exactly what the implementation does, and they were generally not
-documented.
-
-The main difficulty is that different vendors have different views of
-what libraries are, and none of the packages which were examined seemed
-to be confident enough to settle on a single paradigm that just
-@emph{works}.
-
-Ideally, libtool would be a standard that would be implemented as series
-of extensions and modifications to existing library systems to make them
-work consistently. However, it is not an easy task to convince
-operating system developers to mend their evil ways, and people want to
-build shared libraries right now, even on buggy, broken, confused
-operating systems.
-
-For this reason, libtool was designed as an independent shell script.
-It isolates the problems and inconsistencies in library building that
-plague @file{Makefile} writers by wrapping the compiler suite on
-different platforms with a consistent, powerful interface.
-
-With luck, libtool will be useful to and used by the GNU community, and
-that the lessons that were learned in writing it will be taken up by
-designers of future library systems.
-
-@node Libtool paradigm
-@chapter The libtool paradigm
-
-At first, libtool was designed to support an arbitrary number of library
-object types. After libtool was ported to more platforms, a new
-paradigm gradually developed for describing the relationship between
-libraries and programs.
-
-@cindex definition of libraries
-@cindex libraries, definition of
-In summary, ``libraries are programs with multiple entry points, and
-more formally defined interfaces.''
-
-Version 0.7 of libtool was a complete redesign and rewrite of libtool to
-reflect this new paradigm. So far, it has proved to be successful:
-libtool is simpler and more useful than before.
-
-The best way to introduce the libtool paradigm is to contrast it with
-the paradigm of existing library systems, with examples from each. It
-is a new way of thinking, so it may take a little time to absorb, but
-when you understand it, the world becomes simpler.
-
-@node Using libtool
-@chapter Using libtool
-
-@cindex examples of using libtool
-@cindex libtool examples
-It makes little sense to talk about using libtool in your own packages
-until you have seen how it makes your life simpler. The examples in
-this chapter introduce the main features of libtool by comparing the
-standard library building procedure to libtool's operation on two
-different platforms:
-
-@table @samp
-@item a23
-An Ultrix 4.2 platform with only static libraries.
-
-@item burger
-A NetBSD/i386 1.2 platform with shared libraries.
-@end table
-
-You can follow these examples on your own platform, using the
-preconfigured libtool script that was installed with libtool
-(@pxref{Configuring}).
-
-Source files for the following examples are taken from the @file{demo}
-subdirectory of the libtool distribution. Assume that we are building a
-library, @file{libhello}, out of the files @file{foo.c} and
-@file{hello.c}.
-
-Note that the @file{foo.c} source file uses the @code{cos} math library
-function, which is usually found in the standalone math library, and not
-the C library (@pxref{Trig Functions, , Trigonometric Functions, libc,
-The GNU C Library Reference Manual}). So, we need to add @kbd{-lm} to
-the end of the link line whenever we link @file{foo.o} or @file{foo.lo}
-into an executable or a library (@pxref{Inter-library dependencies}).
-
-The same rule applies whenever you use functions that don't appear in
-the standard C library@dots{} you need to add the appropriate
-@kbd{-l@var{name}} flag to the end of the link line when you link
-against those objects.
-
-After we have built that library, we want to create a program by linking
-@file{main.o} against @file{libhello}.
-
-@menu
-* Creating object files:: Compiling object files for libraries.
-* Linking libraries:: Creating libraries from object files.
-* Linking executables:: Linking object files against libtool libraries.
-* Debugging executables:: Running GDB on libtool-generated programs.
-* Installing libraries:: Making libraries available to users.
-* Installing executables:: Making programs available to users.
-* Static libraries:: When shared libraries are not wanted.
-@end menu
-
-@node Creating object files
-@section Creating object files
-
-@cindex compiling object files
-@cindex object files, compiling
-To create an object file from a source file, the compiler is invoked
-with the `-c' flag (and any other desired flags):
-
-@example
-burger$ @kbd{gcc -g -O -c main.c}
-burger$
-@end example
-
-The above compiler command produces an object file, @file{main.o}, from
-the source file @file{main.c}.
-
-For most library systems, creating object files that become part of a
-static library is as simple as creating object files that are linked to
-form an executable:
-
-@example
-burger$ @kbd{gcc -g -O -c foo.c}
-burger$ @kbd{gcc -g -O -c hello.c}
-burger$
-@end example
-
-@cindex position-independent code
-@cindex PIC (position-independent code)
-Shared libraries, however, may only be built from
-@dfn{position-independent code} (PIC). So, special flags must be passed
-to the compiler to tell it to generate PIC rather than the standard
-position-dependent code.
-
-@cindex library object file
-@cindex @samp{.lo} files
-@cindex object files, library
-Since this is a library implementation detail, libtool hides the
-complexity of PIC compiler flags by using separate library object files
-(which end in @samp{.lo} instead of @samp{.o}). On systems without shared
-libraries (or without special PIC compiler flags), these library object
-files are identical to ``standard'' object files.
-
-To create library object files for @file{foo.c} and @file{hello.c},
-simply invoke libtool with the standard compilation command as
-arguments (@pxref{Compile mode}):
-
-@example
-a23$ @kbd{libtool gcc -g -O -c foo.c}
-gcc -g -O -c foo.c
-echo timestamp > foo.lo
-a23$ @kbd{libtool gcc -g -O -c hello.c}
-gcc -g -O -c hello.c
-echo timestamp > hello.lo
-a23$
-@end example
-
-Note that libtool creates two files for each invocation. The @samp{.lo}
-file is a library object, which may be built into a shared library, and
-the @samp{.o} file is a standard object file. On @samp{a23}, the
-library objects are just timestamps, because only static libraries are
-supported.
-
-On shared library systems, libtool automatically inserts the PIC
-generation flags into the compilation command, so that the library
-object and the standard object differ:
-
-@example
-burger$ @kbd{libtool gcc -g -O -c foo.c}
-gcc -g -O -c -fPIC -DPIC foo.c
-mv -f foo.o foo.lo
-gcc -g -O -c foo.c >/dev/null 2>&1
-burger$ @kbd{libtool gcc -g -O -c hello.c}
-gcc -g -O -c -fPIC -DPIC hello.c
-mv -f hello.o hello.lo
-gcc -g -O -c hello.c >/dev/null 2>&1
-burger$
-@end example
-
-Notice that the second run of GCC has its output discarded. This is
-done so that compiler warnings aren't annoyingly duplicated.
-
-@node Linking libraries
-@section Linking libraries
-
-@pindex ar
-Without libtool, the programmer would invoke the @code{ar} command to
-create a static library:
-
-@example
-burger$ @kbd{ar cru libhello.a hello.o foo.o}
-burger$
-@end example
-
-@pindex ranlib
-But of course, that would be too simple, so many systems require that
-you run the @code{ranlib} command on the resulting library (to give it
-better karma, or something):
-
-@example
-burger$ @kbd{ranlib libhello.a}
-burger$
-@end example
-
-It seems more natural to use the C compiler for this task, given
-libtool's ``libraries are programs'' approach. So, on platforms without
-shared libraries, libtool simply acts as a wrapper for the system
-@code{ar} (and possibly @code{ranlib}) commands.
-
-@cindex libtool libraries
-@cindex @samp{.la} files
-Again, the libtool library name differs from the standard name (it has a
-@samp{.la} suffix instead of a @samp{.a} suffix). The arguments to libtool are
-the same ones you would use to produce an executable named
-@file{libhello.la} with your compiler (@pxref{Link mode}):
-
-@example
-a23$ @kbd{libtool gcc -g -O -o libhello.la foo.o hello.o}
-libtool: cannot build libtool library `libhello.la' from non-libtool \
- objects
-a23$
-@end example
-
-Aha! Libtool caught a common error@dots{} trying to build a library
-from standard objects instead of library objects. This doesn't matter
-for static libraries, but on shared library systems, it is of great
-importance.
-
-So, let's try again, this time with the library object files. Remember
-also that we need to add @kbd{-lm} to the link command line because
-@file{foo.c} uses the @code{cos} math library function (@pxref{Using
-libtool}).
-
-Another complication in building shared libraries is that we need to
-specify the path to the directory in which they (eventually) will be
-installed (in this case, @file{/usr/local/lib})@footnote{If you don't
-specify an @code{rpath}, then libtool builds a libtool convenience
-archive, not a shared library (@pxref{Static libraries}).}:
-
-@example
-a23$ @kbd{libtool gcc -g -O -o libhello.la foo.lo hello.lo \
- -rpath /usr/local/lib -lm}
-mkdir @value{objdir}
-ar cru @value{objdir}/libhello.a foo.o hello.o
-ranlib @value{objdir}/libhello.a
-creating libhello.la
-a23$
-@end example
-
-Now, let's try the same trick on the shared library platform:
-
-@example
-burger$ @kbd{libtool gcc -g -O -o libhello.la foo.lo hello.lo \
- -rpath /usr/local/lib -lm}
-mkdir @value{objdir}
-ld -Bshareable -o @value{objdir}/libhello.so.0.0 foo.lo hello.lo -lm
-ar cru @value{objdir}/libhello.a foo.o hello.o
-ranlib @value{objdir}/libhello.a
-creating libhello.la
-burger$
-@end example
-
-Now that's significantly cooler@dots{} libtool just ran an obscure
-@code{ld} command to create a shared library, as well as the static
-library.
-
-@cindex @file{@value{objdir}} subdirectory
-Note how libtool creates extra files in the @file{@value{objdir}}
-subdirectory, rather than the current directory. This feature is to
-make it easier to clean up the build directory, and to help ensure that
-other programs fail horribly if you accidentally forget to use libtool
-when you should.
-
-@node Linking executables
-@section Linking executables
-
-@cindex linking against installed libraries
-If you choose at this point to @dfn{install} the library (put it in a
-permanent location) before linking executables against it, then you
-don't need to use libtool to do the linking. Simply use the appropriate
-@samp{-L} and @samp{-l} flags to specify the library's location.
-
-@cindex buggy system linkers
-Some system linkers insist on encoding the full directory name of each
-shared library in the resulting executable. Libtool has to work around
-this misfeature by special magic to ensure that only permanent directory
-names are put into installed executables.
-
-@cindex security problems with buggy linkers
-@cindex bugs, subtle ones caused by buggy linkers
-The importance of this bug must not be overlooked: it won't cause
-programs to crash in obvious ways. It creates a security hole,
-and possibly even worse, if you are modifying the library source code
-after you have installed the package, you will change the behaviour of
-the installed programs!
-
-So, if you want to link programs against the library before you install
-it, you must use libtool to do the linking.
-
-@cindex linking against uninstalled libraries
-Here's the old way of linking against an uninstalled library:
-
-@example
-burger$ @kbd{gcc -g -O -o hell.old main.o libhello.a -lm}
-burger$
-@end example
-
-Libtool's way is almost the same@footnote{However, you should avoid using
-@samp{-L} or @samp{-l} flags to link against an uninstalled libtool
-library. Just specify the relative path to the @samp{.la} file, such as
-@file{../intl/libintl.la}. This is a design decision to eliminate any
-ambiguity when linking against uninstalled shared libraries.}
-(@pxref{Link mode}):
-
-@example
-a23$ @kbd{libtool gcc -g -O -o hell main.o libhello.la -lm}
-gcc -g -O -o hell main.o ./@value{objdir}/libhello.a -lm
-a23$
-@end example
-
-That looks too simple to be true. All libtool did was transform
-@file{libhello.la} to @file{./@value{objdir}/libhello.a}, but remember
-that @samp{a23} has no shared libraries.
-
-On @samp{burger} the situation is different:
-
-@example
-burger$ @kbd{libtool gcc -g -O -o hell main.o libhello.la -lm}
-gcc -g -O -o @value{objdir}/hell main.o -L./@value{objdir} -R/usr/local/lib -lhello -lm
-creating hell
-burger$
-@end example
-
-@cindex linking with installed libtool libraries
-
-Now assume @file{libhello.la} had already been installed, and you want
-to link a new program with it. You could figure out where it lives by
-yourself, then run:
-
-@example
-burger$ @kbd{gcc -g -O -o test test.o -L/usr/local/lib -lhello}
-@end example
-
-However, unless @file{/usr/local/lib} is in the standard library search
-path, you won't be able to run @code{test}. However, if you use libtool
-to link the already-installed libtool library, it will do The Right
-Thing (TM) for you:
-
-@example
-burger$ @kbd{libtool gcc -g -O -o test test.o /usr/local/lib/libhello.la}
-gcc -g -O -o @value{objdir}/test test.o -Wl,--rpath
--Wl,/usr/local/lib /usr/local/lib/libhello.a -lm
-creating test
-burger$
-@end example
-
-Note that libtool added the necessary run-time path flag, as well as
-@samp{-lm}, the library libhello.la depended upon. Nice, huh?
-
-Since libtool created a wrapper script, you should use libtool to
-install it and debug it too. However, since the program does not depend
-on any uninstalled libtool library, it is probably usable even without
-the wrapper script. Libtool could probably be made smarter to avoid the
-creation of the wrapper script in this case, but this is left as an
-exercise for the reader.
-
-
-@cindex wrapper scripts for programs
-@cindex program wrapper scripts
-Notice that the executable, @code{hell}, was actually created in the
-@file{@value{objdir}} subdirectory. Then, a wrapper script was created
-in the current directory.
-
-On NetBSD 1.2, libtool encodes the installation directory of
-@file{libhello}, by using the @samp{-R/usr/local/lib} compiler flag.
-Then, the wrapper script guarantees that the executable finds the
-correct shared library (the one in @file{./@value{objdir}}) until it is
-properly installed.
-
-Let's compare the two different programs:
-
-@example
-burger$ @kbd{time ./hell.old}
-Welcome to GNU Hell!
-** This is not GNU Hello. There is no built-in mail reader. **
- 0.21 real 0.02 user 0.08 sys
-burger$ @kbd{time ./hell}
-Welcome to GNU Hell!
-** This is not GNU Hello. There is no built-in mail reader. **
- 0.63 real 0.09 user 0.59 sys
-burger$
-@end example
-
-The wrapper script takes significantly longer to execute, but at least
-the results are correct, even though the shared library hasn't been
-installed yet.
-
-So, what about all the space savings that shared libraries are supposed
-to yield?
-
-@example
-burger$ @kbd{ls -l hell.old libhello.a}
--rwxr-xr-x 1 gord gord 15481 Nov 14 12:11 hell.old
--rw-r--r-- 1 gord gord 4274 Nov 13 18:02 libhello.a
-burger$ @kbd{ls -l @value{objdir}/hell @value{objdir}/libhello.*}
--rwxr-xr-x 1 gord gord 11647 Nov 14 12:10 @value{objdir}/hell
--rw-r--r-- 1 gord gord 4274 Nov 13 18:44 @value{objdir}/libhello.a
--rwxr-xr-x 1 gord gord 12205 Nov 13 18:44 @value{objdir}/libhello.so.0.0
-burger$
-@end example
-
-Well, that sucks. Maybe I should just scrap this project and take up
-basket weaving.
-
-Actually, it just proves an important point: shared libraries incur
-overhead because of their (relative) complexity. In this situation, the
-price of being dynamic is eight kilobytes, and the payoff is about four
-kilobytes. So, having a shared @file{libhello} won't be an advantage
-until we link it against at least a few more programs.
-
-@node Debugging executables
-@section Debugging executables
-
-If @file{hell} was a complicated program, you would certainly want to
-test and debug it before installing it on your system. In the above
-section, you saw how the libtool wrapper script makes it possible to run
-the program directly, but unfortunately, this mechanism interferes with
-the debugger:
-
-@example
-burger$ @kbd{gdb hell}
-GDB is free software and you are welcome to distribute copies of it
- under certain conditions; type "show copying" to see the conditions.
-There is no warranty for GDB; type "show warranty" for details.
-GDB 4.16 (i386-unknown-netbsd), (C) 1996 Free Software Foundation, Inc.
-
-"hell": not in executable format: File format not recognized
-
-(gdb) @kbd{quit}
-burger$
-@end example
-
-Sad. It doesn't work because GDB doesn't know where the executable
-lives. So, let's try again, by invoking GDB directly on the executable:
-
-@example
-burger$ @kbd{gdb @value{objdir}/hell}
-trick:/home/src/libtool/demo$ gdb .libs/hell
-GDB is free software and you are welcome to distribute copies of it
- under certain conditions; type "show copying" to see the conditions.
-There is no warranty for GDB; type "show warranty" for details.
-GDB 4.16 (i386-unknown-netbsd), (C) 1996 Free Software Foundation, Inc.
-(gdb) @kbd{break main}
-Breakpoint 1 at 0x8048547: file main.c, line 29.
-(gdb) @kbd{run}
-Starting program: /home/src/libtool/demo/.libs/hell
-/home/src/libtool/demo/.libs/hell: can't load library 'libhello.so.2'
-
-Program exited with code 020.
-(gdb) @kbd{quit}
-burger$
-@end example
-
-Argh. Now GDB complains because it cannot find the shared library that
-@file{hell} is linked against. So, we must use libtool in order to
-properly set the library path and run the debugger. Fortunately, we can
-forget all about the @file{@value{objdir}} directory, and just run it on
-the executable wrapper (@pxref{Execute mode}):
-
-@example
-burger$ @kbd{libtool gdb hell}
-GDB is free software and you are welcome to distribute copies of it
- under certain conditions; type "show copying" to see the conditions.
-There is no warranty for GDB; type "show warranty" for details.
-GDB 4.16 (i386-unknown-netbsd), (C) 1996 Free Software Foundation, Inc.
-(gdb) @kbd{break main}
-Breakpoint 1 at 0x8048547: file main.c, line 29.
-(gdb) @kbd{run}
-Starting program: /home/src/libtool/demo/.libs/hell
-
-Breakpoint 1, main (argc=1, argv=0xbffffc40) at main.c:29
-29 printf ("Welcome to GNU Hell!\n");
-(gdb) @kbd{quit}
-The program is running. Quit anyway (and kill it)? (y or n) @kbd{y}
-burger$
-@end example
-
-@node Installing libraries
-@section Installing libraries
-
-@pindex strip
-Installing libraries on a non-libtool system is quite
-straightforward@dots{} just copy them into place:@footnote{Don't
-accidentally strip the libraries, though, or they will be unusable.}
-
-@pindex su
-@example
-burger$ @kbd{su}
-Password: @kbd{********}
-burger# @kbd{cp libhello.a /usr/local/lib/libhello.a}
-burger#
-@end example
-
-Oops, don't forget the @code{ranlib} command:
-
-@example
-burger# @kbd{ranlib /usr/local/lib/libhello.a}
-burger#
-@end example
-
-@pindex install
-Libtool installation is quite simple, as well. Just use the
-@code{install} or @code{cp} command that you normally would
-(@pxref{Install mode}):
-
-@example
-a23# @kbd{libtool cp libhello.la /usr/local/lib/libhello.la}
-cp libhello.la /usr/local/lib/libhello.la
-cp @value{objdir}/libhello.a /usr/local/lib/libhello.a
-ranlib /usr/local/lib/libhello.a
-a23#
-@end example
-
-Note that the libtool library @file{libhello.la} is also installed, to
-help libtool with uninstallation (@pxref{Uninstall mode}) and linking
-(@pxref{Linking executables}) and to help programs with dlopening
-(@pxref{Dlopened modules}).
-
-Here is the shared library example:
-
-@example
-burger# @kbd{libtool install -c libhello.la /usr/local/lib/libhello.la}
-install -c @value{objdir}/libhello.so.0.0 /usr/local/lib/libhello.so.0.0
-install -c libhello.la /usr/local/lib/libhello.la
-install -c @value{objdir}/libhello.a /usr/local/lib/libhello.a
-ranlib /usr/local/lib/libhello.a
-burger#
-@end example
-
-@cindex stripping libraries
-@cindex libraries, stripping
-It is safe to specify the @samp{-s} (strip symbols) flag if you use a
-BSD-compatible install program when installing libraries.
-Libtool will either ignore the @samp{-s} flag, or will run a program
-that will strip only debugging and compiler symbols from the library.
-
-Once the libraries have been put in place, there may be some additional
-configuration that you need to do before using them. First, you must
-make sure that where the library is installed actually agrees with the
-@samp{-rpath} flag you used to build it.
-
-@cindex postinstallation
-@cindex installation, finishing
-@cindex libraries, finishing installation
-Then, running @samp{libtool -n --finish @var{libdir}} can give you
-further hints on what to do (@pxref{Finish mode}):
-
-@example
-burger# @kbd{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#
-@end example
-
-After you have completed these steps, you can go on to begin using the
-installed libraries. You may also install any executables that depend
-on libraries you created.
-
-@node Installing executables
-@section Installing executables
-
-If you used libtool to link any executables against uninstalled libtool
-libraries (@pxref{Linking executables}), you need to use libtool to
-install the executables after the libraries have been installed
-(@pxref{Installing libraries}).
-
-So, for our Ultrix example, we would run:
-
-@example
-a23# libtool install -c hell /usr/local/bin/hell
-install -c hell /usr/local/bin/hell
-a23#
-@end example
-
-On shared library systems, libtool just ignores the wrapper script and
-installs the correct binary:
-
-@example
-burger# libtool install -c hell /usr/local/bin/hell
-install -c @value{objdir}/hell /usr/local/bin/hell
-burger#
-@end example
-
-@node Static libraries
-@section Linking static libraries
-
-@cindex static linking
-@cindex convenience libraries
-Why return to @code{ar} and @code{ranlib} silliness when you've had a
-taste of libtool? Well, sometimes it is desirable to create a static
-archive that can never be shared. The most frequent case is when you
-have a set of object files that you use to build several different
-programs. You can create a ``convenience library'' out of those
-objects, and link programs with the library, instead of listing all
-object files for every program. This technique is often used to
-overcome GNU automake's lack of support for linking object files built
-from sources in other directories, because it supports linking with
-libraries from other directories. This limitation applies to GNU
-automake up to release 1.4; newer releases should support sources in
-other directories.
-
-If you just want to link this convenience library into programs, then
-you could just ignore libtool entirely, and use the old @code{ar} and
-@code{ranlib} commands (or the corresponding GNU automake
-@samp{_LIBRARIES} rules). You can even install a convenience library
-(but you probably don't want to) using libtool:
-
-@example
-burger$ @kbd{libtool ./install-sh -c libhello.a /local/lib/libhello.a}
-./install-sh -c libhello.a /local/lib/libhello.a
-ranlib /local/lib/libhello.a
-burger$
-@end example
-
-Using libtool for static library installation protects your library from
-being accidentally stripped (if the installer used the @samp{-s} flag),
-as well as automatically running the correct @code{ranlib} command.
-
-But libtool libraries are more than just collections of object files:
-they can also carry library dependency information, which old archives
-do not. If you want to create a libtool static convenience library, you
-can omit the @samp{-rpath} flag and use @samp{-static} to indicate that
-you're only interested in a static library. When you link a program
-with such a library, libtool will actually link all object files and
-dependency libraries into the program.
-
-If you omit both @samp{-rpath} and @samp{-static}, libtool will create a
-convenience library that can be used to create other libtool
-libraries, even shared ones. Just like in the static case, the library
-behaves as an alias to a set of object files and dependency libraries,
-but in this case the object files are suitable for inclusion in shared
-libraries. But be careful not to link a single convenience library,
-directly or indirectly, into a single program or library, otherwise you
-may get errors about symbol redefinitions.
-
+\input texinfo @c -*-texinfo-*-\r
+\r
+@c $Id$\r
+\r
+@c %**start of header\r
+@setfilename libtool.info\r
+@settitle Libtool\r
+@c For double-sided printing, uncomment:\r
+@c @setchapternewpage odd\r
+@c %**end of header\r
+\r
+@include version.texi\r
+@set BUGADDR the libtool bug reporting address @email{bug-libtool@@gnu.org}\r
+@set MAILLIST the libtool mailing list @email{libtool@@gnu.org}\r
+@set objdir .libs\r
+\r
+@dircategory GNU programming tools\r
+@direntry\r
+* Libtool: (libtool). Generic shared library support script.\r
+@end direntry\r
+\r
+@dircategory Individual utilities\r
+@direntry\r
+* libtoolize: (libtool)Invoking libtoolize. Adding libtool support.\r
+@end direntry\r
+\r
+@ifinfo\r
+This file documents GNU Libtool @value{VERSION}\r
+\r
+Copyright (C) 1996-2000 Free Software Foundation, Inc.\r
+\r
+Permission is granted to make and distribute verbatim copies of this\r
+manual provided the copyright notice and this permission notice are\r
+preserved on all copies.\r
+\r
+@ignore\r
+Permission is granted to process this file through TeX and print the\r
+results, provided the printed document carries copying permission notice\r
+identical to this one except for the removal of this paragraph\r
+\r
+\r
+@end ignore\r
+Permission is granted to copy and distribute modified versions of this\r
+manual under the conditions for verbatim copying, provided that the\r
+entire resulting derived work is distributed under the terms of a\r
+permission notice identical to this one.\r
+\r
+Permission is granted to copy and distribute translations of this manual\r
+into another language, under the above conditions for modified versions,\r
+except that this permission notice may be stated in a translation\r
+approved by the Foundation.\r
+@end ifinfo\r
+\r
+\r
+@titlepage\r
+@title GNU Libtool\r
+@subtitle For version @value{VERSION}, @value{UPDATED}\r
+@author Gordon Matzigkeit\r
+@author Alexandre Oliva\r
+@author Thomas Tanner\r
+@author Gary V. Vaughan\r
+\r
+@page\r
+@vskip 0pt plus 1filll\r
+Copyright @copyright{} 1996-2000 Free Software Foundation, Inc.\r
+\r
+Permission is granted to make and distribute verbatim copies of this\r
+manual provided the copyright notice and this permission notice are\r
+preserved on all copies.\r
+\r
+Permission is granted to copy and distribute modified versions of this\r
+manual under the conditions for verbatim copying, provided that the\r
+entire resulting derived work is distributed under the terms of a\r
+permission notice identical to this one.\r
+\r
+Permission is granted to copy and distribute translations of this manual\r
+into another language, under the above conditions for modified versions,\r
+except that this permission notice may be stated in a translation\r
+approved by the Free Software Foundation.\r
+@end titlepage\r
+\r
+@c Put everything in one index (arbitrarily chosen to be the concept index).\r
+@syncodeindex vr cp\r
+@syncodeindex fn cp\r
+@syncodeindex tp cp\r
+@synindex pg cp\r
+\r
+@ifinfo\r
+@node Top, Introduction, (dir), (dir)\r
+@comment node-name, next, previous, up\r
+@top Shared library support for GNU\r
+\r
+This file documents GNU Libtool, a script that allows package developers\r
+to provide generic shared library support. This edition documents\r
+version @value{VERSION}.\r
+\r
+@xref{Reporting bugs}, for information on how to report problems with\r
+libtool.\r
+\r
+@menu\r
+* Introduction:: What the heck is libtool?\r
+* Libtool paradigm:: How libtool's view of libraries is different.\r
+* Using libtool:: Example of using libtool to build libraries.\r
+* Invoking libtool:: Running the @code{libtool} script.\r
+* Integrating libtool:: Using libtool in your own packages.\r
+* Versioning:: Using library interface versions.\r
+* Library tips:: Tips for library interface design.\r
+* Inter-library dependencies:: Libraries that depend on other libraries.\r
+* Dlopened modules:: @code{dlopen}ing libtool-created libraries.\r
+* Using libltdl:: Libtool's portable @code{dlopen} wrapper library.\r
+* Other languages:: Using libtool without a C compiler.\r
+* Troubleshooting:: When libtool doesn't work as advertised.\r
+* Maintaining:: Information used by the libtool maintainer.\r
+* Index:: Full index.\r
+\r
+@detailmenu --- The Detailed Node Listing ---\r
+\r
+Introduction\r
+\r
+* Motivation:: Why does GNU need a libtool?\r
+* Issues:: The problems that need to be addressed.\r
+* Other implementations:: How other people have solved these issues.\r
+* Postmortem:: Learning from past difficulties.\r
+\r
+Using libtool\r
+\r
+* Creating object files:: Compiling object files for libraries.\r
+* Linking libraries:: Creating libraries from object files.\r
+* Linking executables:: Linking object files against libtool libraries.\r
+* Debugging executables:: Running GDB on libtool-generated programs.\r
+* Installing libraries:: Making libraries available to users.\r
+* Installing executables:: Making programs available to users.\r
+* Static libraries:: When shared libraries are not wanted.\r
+\r
+Invoking @code{libtool}\r
+\r
+* Compile mode:: Creating library object files.\r
+* Link mode:: Generating executables and libraries.\r
+* Execute mode:: Debugging libtool-generated programs.\r
+* Install mode:: Making libraries and executables public.\r
+* Finish mode:: Completing a library installation.\r
+* Uninstall mode:: Removing installed executables and libraries.\r
+* Clean mode:: Removing uninstalled executables and libraries.\r
+\r
+Integrating libtool with your package\r
+\r
+* Makefile rules:: Writing @file{Makefile} rules for libtool.\r
+* Using Automake:: Automatically supporting libtool.\r
+* Configuring:: Configuring libtool for a host system.\r
+* Distributing:: What files to distribute with your package.\r
+* Static-only libraries:: Sometimes shared libraries are just a pain.\r
+\r
+Configuring libtool\r
+\r
+* Invoking ltconfig:: @code{ltconfig} command line options.\r
+* ltconfig example:: Manually configuring a @code{libtool}.\r
+* AM_PROG_LIBTOOL:: Configuring @code{libtool} in @file{configure.in}.\r
+\r
+Including libtool in your package\r
+\r
+* Invoking libtoolize:: @code{libtoolize} command line options.\r
+* Autoconf .o macros:: Autoconf macros that set object file names.\r
+\r
+Library interface versions\r
+\r
+* Interfaces:: What are library interfaces?\r
+* Libtool versioning:: Libtool's versioning system.\r
+* Updating version info:: Changing version information before releases.\r
+* Release numbers:: Breaking binary compatibility for aesthetics.\r
+\r
+Tips for interface design\r
+\r
+* C header files:: How to write portable include files.\r
+\r
+Dlopened modules\r
+\r
+* Building modules:: Creating dlopenable objects and libraries.\r
+* Dlpreopening:: Dlopening that works on static platforms.\r
+* Finding the dlname:: Choosing the right file to @code{dlopen}.\r
+* Dlopen issues:: Unresolved problems that need your attention.\r
+\r
+Using libltdl\r
+\r
+* Libltdl interface:: How to use libltdl in your programs.\r
+* Modules for libltdl:: Creating modules that can be @code{dlopen}ed.\r
+* Distributing libltdl:: How to distribute libltdl with your package.\r
+* Module loaders for libltdl:: Creating user defined module loaders.\r
+\r
+Using libtool with other languages\r
+\r
+* C++ libraries::\r
+\r
+Troubleshooting\r
+\r
+* Libtool test suite:: Libtool's self-tests.\r
+* Reporting bugs:: How to report problems with libtool.\r
+\r
+The libtool test suite\r
+\r
+* Test descriptions:: The contents of the test suite.\r
+* When tests fail:: What to do when a test fails.\r
+\r
+Maintenance notes for libtool\r
+\r
+* New ports:: How to port libtool to new systems.\r
+* Tested platforms:: When libtool was last tested.\r
+* Platform quirks:: Information about different library systems.\r
+* libtool script contents:: Configuration information that libtool uses.\r
+* Cheap tricks:: Making libtool maintainership easier.\r
+\r
+Porting libtool to new systems\r
+\r
+* Information sources:: Where to find relevant documentation\r
+* Porting inter-library dependencies:: Implementation details explained\r
+\r
+Platform quirks\r
+\r
+* References:: Finding more information.\r
+* Compilers:: Creating object files from source files.\r
+* Reloadable objects:: Binding object files together.\r
+* Archivers:: Programs that create static archives.\r
+\r
+@end detailmenu\r
+@end menu\r
+\r
+@end ifinfo\r
+\r
+@node Introduction\r
+@chapter Introduction\r
+\r
+In the past, if a source code package developer wanted to take advantage\r
+of the power of shared libraries, he needed to write custom support code\r
+for each platform on which his package ran. He also had to design a\r
+configuration interface so that the package installer could choose what sort of\r
+libraries were built.\r
+\r
+GNU Libtool simplifies the developer's job by encapsulating both the\r
+platform-specific dependencies, and the user interface, in a single\r
+script. GNU Libtool is designed so that the complete functionality of\r
+each host type is available via a generic interface, but nasty quirks\r
+are hidden from the programmer.\r
+\r
+GNU Libtool's consistent interface is reassuring@dots{} users don't need\r
+to read obscure documentation in order to have their favorite source\r
+package build shared libraries. They just run your package\r
+@code{configure} script (or equivalent), and libtool does all the dirty\r
+work.\r
+\r
+There are several examples throughout this document. All assume the\r
+same environment: we want to build a library, @file{libhello}, in a\r
+generic way.\r
+\r
+@file{libhello} could be a shared library, a static library, or\r
+both@dots{} whatever is available on the host system, as long as libtool\r
+has been ported to it.\r
+\r
+This chapter explains the original design philosophy of libtool. Feel\r
+free to skip to the next chapter, unless you are interested in history,\r
+or want to write code to extend libtool in a consistent way.\r
+\r
+@menu\r
+* Motivation:: Why does GNU need a libtool?\r
+* Issues:: The problems that need to be addressed.\r
+* Other implementations:: How other people have solved these issues.\r
+* Postmortem:: Learning from past difficulties.\r
+@end menu\r
+\r
+@node Motivation\r
+@section Motivation for writing libtool\r
+\r
+@cindex motivation for writing libtool\r
+@cindex design philosophy\r
+Since early 1995, several different GNU developers have recognized the\r
+importance of having shared library support for their packages. The\r
+primary motivation for such a change is to encourage modularity and\r
+reuse of code (both conceptually and physically) in GNU programs.\r
+\r
+Such a demand means that the way libraries are built in GNU packages\r
+needs to be general, to allow for any library type the package installer\r
+might want. The problem is compounded by the absence of a standard\r
+procedure for creating shared libraries on different platforms.\r
+\r
+The following sections outline the major issues facing shared library\r
+support in GNU, and how shared library support could be standardized\r
+with libtool.\r
+\r
+@cindex specifications for libtool\r
+@cindex libtool specifications\r
+The following specifications were used in developing and evaluating this\r
+system:\r
+\r
+@enumerate\r
+@item\r
+The system must be as elegant as possible.\r
+\r
+@item\r
+The system must be fully integrated with the GNU Autoconf and Automake\r
+utilities, so that it will be easy for GNU maintainers to use. However,\r
+the system must not require these tools, so that it can be used by\r
+non-GNU packages.\r
+\r
+@item\r
+Portability to other (non-GNU) architectures and tools is desirable.\r
+@end enumerate\r
+\r
+@node Issues\r
+@section Implementation issues\r
+\r
+@cindex tricky design issues\r
+@cindex design issues\r
+The following issues need to be addressed in any reusable shared library\r
+system, specifically libtool:\r
+\r
+@enumerate\r
+@item\r
+The package installer should be able to control what sort of libraries\r
+are built.\r
+\r
+@item\r
+It can be tricky to run dynamically linked programs whose libraries have\r
+not yet been installed. @code{LD_LIBRARY_PATH} must be set properly (if\r
+it is supported), or programs fail to run.\r
+\r
+@item\r
+The system must operate consistently even on hosts which don't support\r
+shared libraries.\r
+\r
+@item\r
+The commands required to build shared libraries may differ wildly from\r
+host to host. These need to be determined at configure time in\r
+a consistent way.\r
+\r
+@item\r
+It is not always obvious with which suffix a shared library should be\r
+installed. This makes it difficult for @file{Makefile} rules, since they\r
+generally assume that file names are the same from host to host.\r
+\r
+@item\r
+The system needs a simple library version number abstraction, so that\r
+shared libraries can be upgraded in place. The programmer should be\r
+informed how to design the interfaces to the library to maximize binary\r
+compatibility.\r
+\r
+@item\r
+The install @file{Makefile} target should warn the package installer to set\r
+the proper environment variables (@code{LD_LIBRARY_PATH} or equivalent),\r
+or run @code{ldconfig}.\r
+@end enumerate\r
+\r
+@node Other implementations\r
+@section Other implementations\r
+\r
+Even before libtool was developed, many free software packages built and\r
+installed their own shared libraries. At first, these packages were\r
+examined to avoid reinventing existing features.\r
+\r
+Now it is clear that none of these packages have documented the details\r
+of shared library systems that libtool requires. So, other packages\r
+have been more or less abandoned as influences.\r
+\r
+@node Postmortem\r
+@section A postmortem analysis of other implementations\r
+\r
+@cindex other implementations, flaws in\r
+@cindex reusability of library systems\r
+In all fairness, each of the implementations that were examined do the\r
+job that they were intended to do, for a number of different host\r
+systems. However, none of these solutions seem to function well as a\r
+generalized, reusable component.\r
+\r
+@cindex complexity of library systems\r
+Most were too complex to use (much less modify) without understanding\r
+exactly what the implementation does, and they were generally not\r
+documented.\r
+\r
+The main difficulty is that different vendors have different views of\r
+what libraries are, and none of the packages which were examined seemed\r
+to be confident enough to settle on a single paradigm that just\r
+@emph{works}.\r
+\r
+Ideally, libtool would be a standard that would be implemented as series\r
+of extensions and modifications to existing library systems to make them\r
+work consistently. However, it is not an easy task to convince\r
+operating system developers to mend their evil ways, and people want to\r
+build shared libraries right now, even on buggy, broken, confused\r
+operating systems.\r
+\r
+For this reason, libtool was designed as an independent shell script.\r
+It isolates the problems and inconsistencies in library building that\r
+plague @file{Makefile} writers by wrapping the compiler suite on\r
+different platforms with a consistent, powerful interface.\r
+\r
+With luck, libtool will be useful to and used by the GNU community, and\r
+that the lessons that were learned in writing it will be taken up by\r
+designers of future library systems.\r
+\r
+@node Libtool paradigm\r
+@chapter The libtool paradigm\r
+\r
+At first, libtool was designed to support an arbitrary number of library\r
+object types. After libtool was ported to more platforms, a new\r
+paradigm gradually developed for describing the relationship between\r
+libraries and programs.\r
+\r
+@cindex definition of libraries\r
+@cindex libraries, definition of\r
+In summary, ``libraries are programs with multiple entry points, and\r
+more formally defined interfaces.''\r
+\r
+Version 0.7 of libtool was a complete redesign and rewrite of libtool to\r
+reflect this new paradigm. So far, it has proved to be successful:\r
+libtool is simpler and more useful than before.\r
+\r
+The best way to introduce the libtool paradigm is to contrast it with\r
+the paradigm of existing library systems, with examples from each. It\r
+is a new way of thinking, so it may take a little time to absorb, but\r
+when you understand it, the world becomes simpler.\r
+\r
+@node Using libtool\r
+@chapter Using libtool\r
+\r
+@cindex examples of using libtool\r
+@cindex libtool examples\r
+It makes little sense to talk about using libtool in your own packages\r
+until you have seen how it makes your life simpler. The examples in\r
+this chapter introduce the main features of libtool by comparing the\r
+standard library building procedure to libtool's operation on two\r
+different platforms:\r
+\r
+@table @samp\r
+@item a23\r
+An Ultrix 4.2 platform with only static libraries.\r
+\r
+@item burger\r
+A NetBSD/i386 1.2 platform with shared libraries.\r
+@end table\r
+\r
+You can follow these examples on your own platform, using the\r
+preconfigured libtool script that was installed with libtool\r
+(@pxref{Configuring}).\r
+\r
+Source files for the following examples are taken from the @file{demo}\r
+subdirectory of the libtool distribution. Assume that we are building a\r
+library, @file{libhello}, out of the files @file{foo.c} and\r
+@file{hello.c}.\r
+\r
+Note that the @file{foo.c} source file uses the @code{cos} math library\r
+function, which is usually found in the standalone math library, and not\r
+the C library (@pxref{Trig Functions, , Trigonometric Functions, libc,\r
+The GNU C Library Reference Manual}). So, we need to add @kbd{-lm} to\r
+the end of the link line whenever we link @file{foo.o} or @file{foo.lo}\r
+into an executable or a library (@pxref{Inter-library dependencies}).\r
+\r
+The same rule applies whenever you use functions that don't appear in\r
+the standard C library@dots{} you need to add the appropriate\r
+@kbd{-l@var{name}} flag to the end of the link line when you link\r
+against those objects.\r
+\r
+After we have built that library, we want to create a program by linking\r
+@file{main.o} against @file{libhello}.\r
+\r
+@menu\r
+* Creating object files:: Compiling object files for libraries.\r
+* Linking libraries:: Creating libraries from object files.\r
+* Linking executables:: Linking object files against libtool libraries.\r
+* Debugging executables:: Running GDB on libtool-generated programs.\r
+* Installing libraries:: Making libraries available to users.\r
+* Installing executables:: Making programs available to users.\r
+* Static libraries:: When shared libraries are not wanted.\r
+@end menu\r
+\r
+@node Creating object files\r
+@section Creating object files\r
+\r
+@cindex compiling object files\r
+@cindex object files, compiling\r
+To create an object file from a source file, the compiler is invoked\r
+with the `-c' flag (and any other desired flags):\r
+\r
+@example\r
+burger$ @kbd{gcc -g -O -c main.c}\r
+burger$\r
+@end example\r
+\r
+The above compiler command produces an object file, @file{main.o}, from\r
+the source file @file{main.c}.\r
+\r
+For most library systems, creating object files that become part of a\r
+static library is as simple as creating object files that are linked to\r
+form an executable:\r
+\r
+@example\r
+burger$ @kbd{gcc -g -O -c foo.c}\r
+burger$ @kbd{gcc -g -O -c hello.c}\r
+burger$\r
+@end example\r
+\r
+@cindex position-independent code\r
+@cindex PIC (position-independent code)\r
+Shared libraries, however, may only be built from\r
+@dfn{position-independent code} (PIC). So, special flags must be passed\r
+to the compiler to tell it to generate PIC rather than the standard\r
+position-dependent code.\r
+\r
+@cindex library object file\r
+@cindex @samp{.lo} files\r
+@cindex object files, library\r
+Since this is a library implementation detail, libtool hides the\r
+complexity of PIC compiler flags by using separate library object files\r
+(which end in @samp{.lo} instead of @samp{.o}). On systems without shared\r
+libraries (or without special PIC compiler flags), these library object\r
+files are identical to ``standard'' object files.\r
+\r
+To create library object files for @file{foo.c} and @file{hello.c},\r
+simply invoke libtool with the standard compilation command as\r
+arguments (@pxref{Compile mode}):\r
+\r
+@example\r
+a23$ @kbd{libtool gcc -g -O -c foo.c}\r
+gcc -g -O -c foo.c\r
+echo timestamp > foo.lo\r
+a23$ @kbd{libtool gcc -g -O -c hello.c}\r
+gcc -g -O -c hello.c\r
+echo timestamp > hello.lo\r
+a23$\r
+@end example\r
+\r
+Note that libtool creates two files for each invocation. The @samp{.lo}\r
+file is a library object, which may be built into a shared library, and\r
+the @samp{.o} file is a standard object file. On @samp{a23}, the\r
+library objects are just timestamps, because only static libraries are\r
+supported.\r
+\r
+On shared library systems, libtool automatically inserts the PIC\r
+generation flags into the compilation command, so that the library\r
+object and the standard object differ:\r
+\r
+@example\r
+burger$ @kbd{libtool gcc -g -O -c foo.c}\r
+gcc -g -O -c -fPIC -DPIC foo.c\r
+mv -f foo.o foo.lo\r
+gcc -g -O -c foo.c >/dev/null 2>&1\r
+burger$ @kbd{libtool gcc -g -O -c hello.c}\r
+gcc -g -O -c -fPIC -DPIC hello.c\r
+mv -f hello.o hello.lo\r
+gcc -g -O -c hello.c >/dev/null 2>&1\r
+burger$\r
+@end example\r
+\r
+Notice that the second run of GCC has its output discarded. This is\r
+done so that compiler warnings aren't annoyingly duplicated.\r
+\r
+@node Linking libraries\r
+@section Linking libraries\r
+\r
+@pindex ar\r
+Without libtool, the programmer would invoke the @code{ar} command to\r
+create a static library:\r
+\r
+@example\r
+burger$ @kbd{ar cru libhello.a hello.o foo.o}\r
+burger$\r
+@end example\r
+\r
+@pindex ranlib\r
+But of course, that would be too simple, so many systems require that\r
+you run the @code{ranlib} command on the resulting library (to give it\r
+better karma, or something):\r
+\r
+@example\r
+burger$ @kbd{ranlib libhello.a}\r
+burger$\r
+@end example\r
+\r
+It seems more natural to use the C compiler for this task, given\r
+libtool's ``libraries are programs'' approach. So, on platforms without\r
+shared libraries, libtool simply acts as a wrapper for the system\r
+@code{ar} (and possibly @code{ranlib}) commands.\r
+\r
+@cindex libtool libraries\r
+@cindex @samp{.la} files\r
+Again, the libtool library name differs from the standard name (it has a\r
+@samp{.la} suffix instead of a @samp{.a} suffix). The arguments to libtool are\r
+the same ones you would use to produce an executable named\r
+@file{libhello.la} with your compiler (@pxref{Link mode}):\r
+\r
+@example\r
+a23$ @kbd{libtool gcc -g -O -o libhello.la foo.o hello.o}\r
+libtool: cannot build libtool library `libhello.la' from non-libtool \\r
+ objects\r
+a23$\r
+@end example\r
+\r
+Aha! Libtool caught a common error@dots{} trying to build a library\r
+from standard objects instead of library objects. This doesn't matter\r
+for static libraries, but on shared library systems, it is of great\r
+importance.\r
+\r
+So, let's try again, this time with the library object files. Remember\r
+also that we need to add @kbd{-lm} to the link command line because\r
+@file{foo.c} uses the @code{cos} math library function (@pxref{Using\r
+libtool}).\r
+\r
+Another complication in building shared libraries is that we need to\r
+specify the path to the directory in which they (eventually) will be\r
+installed (in this case, @file{/usr/local/lib})@footnote{If you don't\r
+specify an @code{rpath}, then libtool builds a libtool convenience\r
+archive, not a shared library (@pxref{Static libraries}).}:\r
+\r
+@example\r
+a23$ @kbd{libtool gcc -g -O -o libhello.la foo.lo hello.lo \\r
+ -rpath /usr/local/lib -lm}\r
+mkdir @value{objdir}\r
+ar cru @value{objdir}/libhello.a foo.o hello.o\r
+ranlib @value{objdir}/libhello.a\r
+creating libhello.la\r
+a23$\r
+@end example\r
+\r
+Now, let's try the same trick on the shared library platform:\r
+\r
+@example\r
+burger$ @kbd{libtool gcc -g -O -o libhello.la foo.lo hello.lo \\r
+ -rpath /usr/local/lib -lm}\r
+mkdir @value{objdir}\r
+ld -Bshareable -o @value{objdir}/libhello.so.0.0 foo.lo hello.lo -lm\r
+ar cru @value{objdir}/libhello.a foo.o hello.o\r
+ranlib @value{objdir}/libhello.a\r
+creating libhello.la\r
+burger$\r
+@end example\r
+\r
+Now that's significantly cooler@dots{} libtool just ran an obscure\r
+@code{ld} command to create a shared library, as well as the static\r
+library.\r
+\r
+@cindex @file{@value{objdir}} subdirectory\r
+Note how libtool creates extra files in the @file{@value{objdir}}\r
+subdirectory, rather than the current directory. This feature is to\r
+make it easier to clean up the build directory, and to help ensure that\r
+other programs fail horribly if you accidentally forget to use libtool\r
+when you should.\r
+\r
+@node Linking executables\r
+@section Linking executables\r
+\r
+@cindex linking against installed libraries\r
+If you choose at this point to @dfn{install} the library (put it in a\r
+permanent location) before linking executables against it, then you\r
+don't need to use libtool to do the linking. Simply use the appropriate\r
+@samp{-L} and @samp{-l} flags to specify the library's location.\r
+\r
+@cindex buggy system linkers\r
+Some system linkers insist on encoding the full directory name of each\r
+shared library in the resulting executable. Libtool has to work around\r
+this misfeature by special magic to ensure that only permanent directory\r
+names are put into installed executables.\r
+\r
+@cindex security problems with buggy linkers\r
+@cindex bugs, subtle ones caused by buggy linkers\r
+The importance of this bug must not be overlooked: it won't cause\r
+programs to crash in obvious ways. It creates a security hole,\r
+and possibly even worse, if you are modifying the library source code\r
+after you have installed the package, you will change the behaviour of\r
+the installed programs!\r
+\r
+So, if you want to link programs against the library before you install\r
+it, you must use libtool to do the linking.\r
+\r
+@cindex linking against uninstalled libraries\r
+Here's the old way of linking against an uninstalled library:\r
+\r
+@example\r
+burger$ @kbd{gcc -g -O -o hell.old main.o libhello.a -lm}\r
+burger$\r
+@end example\r
+\r
+Libtool's way is almost the same@footnote{However, you should avoid using\r
+@samp{-L} or @samp{-l} flags to link against an uninstalled libtool\r
+library. Just specify the relative path to the @samp{.la} file, such as\r
+@file{../intl/libintl.la}. This is a design decision to eliminate any\r
+ambiguity when linking against uninstalled shared libraries.}\r
+(@pxref{Link mode}):\r
+\r
+@example\r
+a23$ @kbd{libtool gcc -g -O -o hell main.o libhello.la -lm}\r
+gcc -g -O -o hell main.o ./@value{objdir}/libhello.a -lm\r
+a23$\r
+@end example\r
+\r
+That looks too simple to be true. All libtool did was transform\r
+@file{libhello.la} to @file{./@value{objdir}/libhello.a}, but remember\r
+that @samp{a23} has no shared libraries.\r
+\r
+On @samp{burger} the situation is different:\r
+\r
+@example\r
+burger$ @kbd{libtool gcc -g -O -o hell main.o libhello.la -lm}\r
+gcc -g -O -o @value{objdir}/hell main.o -L./@value{objdir} -R/usr/local/lib -lhello -lm\r
+creating hell\r
+burger$\r
+@end example\r
+\r
+@cindex linking with installed libtool libraries\r
+\r
+Now assume @file{libhello.la} had already been installed, and you want\r
+to link a new program with it. You could figure out where it lives by\r
+yourself, then run:\r
+\r
+@example\r
+burger$ @kbd{gcc -g -O -o test test.o -L/usr/local/lib -lhello}\r
+@end example\r
+\r
+However, unless @file{/usr/local/lib} is in the standard library search\r
+path, you won't be able to run @code{test}. However, if you use libtool\r
+to link the already-installed libtool library, it will do The Right\r
+Thing (TM) for you:\r
+\r
+@example\r
+burger$ @kbd{libtool gcc -g -O -o test test.o /usr/local/lib/libhello.la}\r
+gcc -g -O -o @value{objdir}/test test.o -Wl,--rpath\r
+-Wl,/usr/local/lib /usr/local/lib/libhello.a -lm\r
+creating test\r
+burger$\r
+@end example\r
+\r
+Note that libtool added the necessary run-time path flag, as well as\r
+@samp{-lm}, the library libhello.la depended upon. Nice, huh?\r
+\r
+Since libtool created a wrapper script, you should use libtool to\r
+install it and debug it too. However, since the program does not depend \r
+on any uninstalled libtool library, it is probably usable even without\r
+the wrapper script. Libtool could probably be made smarter to avoid the \r
+creation of the wrapper script in this case, but this is left as an\r
+exercise for the reader.\r
+\r
+\r
+@cindex wrapper scripts for programs\r
+@cindex program wrapper scripts\r
+Notice that the executable, @code{hell}, was actually created in the\r
+@file{@value{objdir}} subdirectory. Then, a wrapper script was created\r
+in the current directory.\r
+\r
+On NetBSD 1.2, libtool encodes the installation directory of\r
+@file{libhello}, by using the @samp{-R/usr/local/lib} compiler flag.\r
+Then, the wrapper script guarantees that the executable finds the\r
+correct shared library (the one in @file{./@value{objdir}}) until it is\r
+properly installed.\r
+\r
+Let's compare the two different programs:\r
+\r
+@example\r
+burger$ @kbd{time ./hell.old}\r
+Welcome to GNU Hell!\r
+** This is not GNU Hello. There is no built-in mail reader. **\r
+ 0.21 real 0.02 user 0.08 sys\r
+burger$ @kbd{time ./hell}\r
+Welcome to GNU Hell!\r
+** This is not GNU Hello. There is no built-in mail reader. **\r
+ 0.63 real 0.09 user 0.59 sys\r
+burger$\r
+@end example\r
+\r
+The wrapper script takes significantly longer to execute, but at least\r
+the results are correct, even though the shared library hasn't been\r
+installed yet.\r
+\r
+So, what about all the space savings that shared libraries are supposed\r
+to yield?\r
+\r
+@example\r
+burger$ @kbd{ls -l hell.old libhello.a}\r
+-rwxr-xr-x 1 gord gord 15481 Nov 14 12:11 hell.old\r
+-rw-r--r-- 1 gord gord 4274 Nov 13 18:02 libhello.a\r
+burger$ @kbd{ls -l @value{objdir}/hell @value{objdir}/libhello.*}\r
+-rwxr-xr-x 1 gord gord 11647 Nov 14 12:10 @value{objdir}/hell\r
+-rw-r--r-- 1 gord gord 4274 Nov 13 18:44 @value{objdir}/libhello.a\r
+-rwxr-xr-x 1 gord gord 12205 Nov 13 18:44 @value{objdir}/libhello.so.0.0\r
+burger$\r
+@end example\r
+\r
+Well, that sucks. Maybe I should just scrap this project and take up\r
+basket weaving.\r
+\r
+Actually, it just proves an important point: shared libraries incur\r
+overhead because of their (relative) complexity. In this situation, the\r
+price of being dynamic is eight kilobytes, and the payoff is about four\r
+kilobytes. So, having a shared @file{libhello} won't be an advantage\r
+until we link it against at least a few more programs.\r
+\r
+@node Debugging executables\r
+@section Debugging executables\r
+\r
+If @file{hell} was a complicated program, you would certainly want to\r
+test and debug it before installing it on your system. In the above\r
+section, you saw how the libtool wrapper script makes it possible to run\r
+the program directly, but unfortunately, this mechanism interferes with\r
+the debugger:\r
+\r
+@example\r
+burger$ @kbd{gdb hell}\r
+GDB is free software and you are welcome to distribute copies of it\r
+ under certain conditions; type "show copying" to see the conditions.\r
+There is no warranty for GDB; type "show warranty" for details.\r
+GDB 4.16 (i386-unknown-netbsd), (C) 1996 Free Software Foundation, Inc.\r
+\r
+"hell": not in executable format: File format not recognized\r
+\r
+(gdb) @kbd{quit}\r
+burger$\r
+@end example\r
+\r
+Sad. It doesn't work because GDB doesn't know where the executable\r
+lives. So, let's try again, by invoking GDB directly on the executable:\r
+\r
+@example\r
+burger$ @kbd{gdb @value{objdir}/hell}\r
+trick:/home/src/libtool/demo$ gdb .libs/hell\r
+GDB is free software and you are welcome to distribute copies of it\r
+ under certain conditions; type "show copying" to see the conditions.\r
+There is no warranty for GDB; type "show warranty" for details.\r
+GDB 4.16 (i386-unknown-netbsd), (C) 1996 Free Software Foundation, Inc.\r
+(gdb) @kbd{break main}\r
+Breakpoint 1 at 0x8048547: file main.c, line 29.\r
+(gdb) @kbd{run}\r
+Starting program: /home/src/libtool/demo/.libs/hell\r
+/home/src/libtool/demo/.libs/hell: can't load library 'libhello.so.2'\r
+\r
+Program exited with code 020.\r
+(gdb) @kbd{quit}\r
+burger$\r
+@end example\r
+\r
+Argh. Now GDB complains because it cannot find the shared library that\r
+@file{hell} is linked against. So, we must use libtool in order to\r
+properly set the library path and run the debugger. Fortunately, we can\r
+forget all about the @file{@value{objdir}} directory, and just run it on\r
+the executable wrapper (@pxref{Execute mode}):\r
+\r
+@example\r
+burger$ @kbd{libtool gdb hell}\r
+GDB is free software and you are welcome to distribute copies of it\r
+ under certain conditions; type "show copying" to see the conditions.\r
+There is no warranty for GDB; type "show warranty" for details.\r
+GDB 4.16 (i386-unknown-netbsd), (C) 1996 Free Software Foundation, Inc.\r
+(gdb) @kbd{break main}\r
+Breakpoint 1 at 0x8048547: file main.c, line 29.\r
+(gdb) @kbd{run}\r
+Starting program: /home/src/libtool/demo/.libs/hell\r
+\r
+Breakpoint 1, main (argc=1, argv=0xbffffc40) at main.c:29\r
+29 printf ("Welcome to GNU Hell!\n");\r
+(gdb) @kbd{quit}\r
+The program is running. Quit anyway (and kill it)? (y or n) @kbd{y}\r
+burger$\r
+@end example\r
+\r
+@node Installing libraries\r
+@section Installing libraries\r
+\r
+@pindex strip\r
+Installing libraries on a non-libtool system is quite\r
+straightforward@dots{} just copy them into place:@footnote{Don't\r
+accidentally strip the libraries, though, or they will be unusable.}\r
+\r
+@pindex su\r
+@example\r
+burger$ @kbd{su}\r
+Password: @kbd{********}\r
+burger# @kbd{cp libhello.a /usr/local/lib/libhello.a}\r
+burger#\r
+@end example\r
+\r
+Oops, don't forget the @code{ranlib} command:\r
+\r
+@example\r
+burger# @kbd{ranlib /usr/local/lib/libhello.a}\r
+burger#\r
+@end example\r
+\r
+@pindex install\r
+Libtool installation is quite simple, as well. Just use the\r
+@code{install} or @code{cp} command that you normally would\r
+(@pxref{Install mode}):\r
+\r
+@example\r
+a23# @kbd{libtool cp libhello.la /usr/local/lib/libhello.la}\r
+cp libhello.la /usr/local/lib/libhello.la\r
+cp @value{objdir}/libhello.a /usr/local/lib/libhello.a\r
+ranlib /usr/local/lib/libhello.a\r
+a23#\r
+@end example\r
+\r
+Note that the libtool library @file{libhello.la} is also installed, to\r
+help libtool with uninstallation (@pxref{Uninstall mode}) and linking\r
+(@pxref{Linking executables}) and to help programs with dlopening\r
+(@pxref{Dlopened modules}).\r
+\r
+Here is the shared library example:\r
+\r
+@example\r
+burger# @kbd{libtool install -c libhello.la /usr/local/lib/libhello.la}\r
+install -c @value{objdir}/libhello.so.0.0 /usr/local/lib/libhello.so.0.0\r
+install -c libhello.la /usr/local/lib/libhello.la\r
+install -c @value{objdir}/libhello.a /usr/local/lib/libhello.a\r
+ranlib /usr/local/lib/libhello.a\r
+burger#\r
+@end example\r
+\r
+@cindex stripping libraries\r
+@cindex libraries, stripping\r
+It is safe to specify the @samp{-s} (strip symbols) flag if you use a\r
+BSD-compatible install program when installing libraries.\r
+Libtool will either ignore the @samp{-s} flag, or will run a program\r
+that will strip only debugging and compiler symbols from the library.\r
+\r
+Once the libraries have been put in place, there may be some additional\r
+configuration that you need to do before using them. First, you must\r
+make sure that where the library is installed actually agrees with the\r
+@samp{-rpath} flag you used to build it.\r
+\r
+@cindex postinstallation\r
+@cindex installation, finishing\r
+@cindex libraries, finishing installation\r
+Then, running @samp{libtool -n --finish @var{libdir}} can give you\r
+further hints on what to do (@pxref{Finish mode}):\r
+\r
+@example\r
+burger# @kbd{libtool -n --finish /usr/local/lib}\r
+PATH="$PATH:/sbin" ldconfig -m /usr/local/lib\r
+-----------------------------------------------------------------\r
+Libraries have been installed in:\r
+ /usr/local/lib\r
+\r
+To link against installed libraries in a given directory, LIBDIR,\r
+you must use the `-LLIBDIR' flag during linking.\r
+\r
+ You will also need to do one of the following:\r
+ - add LIBDIR to the `LD_LIBRARY_PATH' environment variable\r
+ during execution\r
+ - add LIBDIR to the `LD_RUN_PATH' environment variable\r
+ during linking\r
+ - use the `-RLIBDIR' linker flag\r
+\r
+See any operating system documentation about shared libraries for\r
+more information, such as the ld and ld.so manual pages.\r
+-----------------------------------------------------------------\r
+burger#\r
+@end example\r
+\r
+After you have completed these steps, you can go on to begin using the\r
+installed libraries. You may also install any executables that depend\r
+on libraries you created.\r
+\r
+@node Installing executables\r
+@section Installing executables\r
+\r
+If you used libtool to link any executables against uninstalled libtool\r
+libraries (@pxref{Linking executables}), you need to use libtool to\r
+install the executables after the libraries have been installed\r
+(@pxref{Installing libraries}).\r
+\r
+So, for our Ultrix example, we would run:\r
+\r
+@example\r
+a23# libtool install -c hell /usr/local/bin/hell\r
+install -c hell /usr/local/bin/hell\r
+a23#\r
+@end example\r
+\r
+On shared library systems, libtool just ignores the wrapper script and\r
+installs the correct binary:\r
+\r
+@example\r
+burger# libtool install -c hell /usr/local/bin/hell\r
+install -c @value{objdir}/hell /usr/local/bin/hell\r
+burger#\r
+@end example\r
+\r
+@node Static libraries\r
+@section Linking static libraries\r
+\r
+@cindex static linking\r
+@cindex convenience libraries\r
+Why return to @code{ar} and @code{ranlib} silliness when you've had a\r
+taste of libtool? Well, sometimes it is desirable to create a static\r
+archive that can never be shared. The most frequent case is when you\r
+have a set of object files that you use to build several different\r
+programs. You can create a ``convenience library'' out of those\r
+objects, and link programs with the library, instead of listing all\r
+object files for every program. This technique is often used to\r
+overcome GNU automake's lack of support for linking object files built\r
+from sources in other directories, because it supports linking with\r
+libraries from other directories. This limitation applies to GNU\r
+automake up to release 1.4; newer releases should support sources in\r
+other directories.\r
+\r
+If you just want to link this convenience library into programs, then\r
+you could just ignore libtool entirely, and use the old @code{ar} and\r
+@code{ranlib} commands (or the corresponding GNU automake\r
+@samp{_LIBRARIES} rules). You can even install a convenience library\r
+(but you probably don't want to) using libtool:\r
+\r
+@example\r
+burger$ @kbd{libtool ./install-sh -c libhello.a /local/lib/libhello.a}\r
+./install-sh -c libhello.a /local/lib/libhello.a\r
+ranlib /local/lib/libhello.a\r
+burger$\r
+@end example\r
+\r
+Using libtool for static library installation protects your library from\r
+being accidentally stripped (if the installer used the @samp{-s} flag),\r
+as well as automatically running the correct @code{ranlib} command.\r
+\r
+But libtool libraries are more than just collections of object files:\r
+they can also carry library dependency information, which old archives\r
+do not. If you want to create a libtool static convenience library, you \r
+can omit the @samp{-rpath} flag and use @samp{-static} to indicate that\r
+you're only interested in a static library. When you link a program\r
+with such a library, libtool will actually link all object files and\r
+dependency libraries into the program.\r
+\r
+If you omit both @samp{-rpath} and @samp{-static}, libtool will create a\r
+convenience library that can be used to create other libtool\r
+libraries, even shared ones. Just like in the static case, the library\r
+behaves as an alias to a set of object files and dependency libraries,\r
+but in this case the object files are suitable for inclusion in shared\r
+libraries. But be careful not to link a single convenience library,\r
+directly or indirectly, into a single program or library, otherwise you\r
+may get errors about symbol redefinitions.\r
+\r
When GNU automake is used, you should use @code{noinst_LTLIBRARIES}\r
instead of @code{lib_LTLIBRARIES} for convenience libraries, so that\r
the @samp{-rpath} option is not passed when they are linked.\r
\r
-As a rule of thumb, link a libtool convenience library into at most one
-libtool library, and never into a program, and link libtool static
-convenience libraries only into programs, and only if you need to carry
-library dependency information to the user of the static convenience
-library.
-
-@cindex standalone binaries
-Another common situation where static linking is desirable is in
-creating a standalone binary. Use libtool to do the linking and add the
-@samp{-all-static} flag.
-
-@node Invoking libtool
-@chapter Invoking @code{libtool}
-@pindex libtool
-@cindex libtool command options
-@cindex options, libtool command
-@cindex command options, libtool
-
-The @code{libtool} program has the following synopsis:
-
-@example
-libtool [@var{option}]@dots{} [@var{mode-arg}]@dots{}
-@end example
-
-@noindent
-and accepts the following options:
-
-@table @samp
-@item --config
-Display libtool configuration variables and exit.
-
-@item --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 @code{less} (or
-@code{more}) or redirect to a file.
-
-@item -n
-@itemx --dry-run
-Don't create, modify, or delete any files, just show what commands would
-be executed by libtool.
-
-@item --features
-Display basic configuration options. This provides a way for packages
-to determine whether shared or static libraries will be built.
-
-@item --finish
-Same as @samp{--mode=finish}.
-
-@item --help
-Display a help message and exit. If @samp{--mode=@var{mode}} is
-specified, then detailed help for @var{mode} is
-displayed.
-
-@item --tag=@var{tag}
-Select configuration tag @var{tag}. Additional configuration tags can
-be created with @code{ltconfig --add-tag}. Multiple @samp{--tag} flags
-can be specified. In general, one tag will completely replace the
-configuration of the other, but the two pre-defined configuration tags,
-@samp{disable-shared} and @samp{disable-static}, if used @emph{after}
-any other, cause libtool not to create shared or static libraries,
-respectively, regardless of the corresponding flags used for
-@code{ltconfig}.
-
-@item --mode=@var{mode}
-Use @var{mode} as the operation mode. By default, the operation mode is
-inferred from the @var{mode-args}.
-
-If @var{mode} is specified, it must be one of the following:
-
-@table @samp
-@item compile
-Compile a source file into a libtool object.
-
-@item execute
-Automatically set the library path so that another program can use
-uninstalled libtool-generated programs or libraries.
-
-@item finish
-Complete the installation of libtool libraries on the system.
-
-@item install
-Install libraries or executables.
-
-@item link
-Create a library or an executable.
-
-@item uninstall
-Delete installed libraries or executables.
-
-@item clean
-Delete uninstalled libraries or executables.
-@end table
-
-@item --version
-Print libtool version information and exit.
-@end table
-
-The @var{mode-args} are a variable number of arguments, depending on the
-selected operation mode. In general, each @var{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 installed executables and libraries.
-* Clean mode:: Removing uninstalled executables and libraries.
-@end menu
-
-@node Compile mode
-@section Compile mode
-@cindex mode, compile
-@cindex compile mode
-
-For @dfn{compile} mode, @var{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 @samp{-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. @samp{.c} for C source code) with the library object suffix,
-@samp{.lo}.
-
-If shared libraries are being built, any necessary PIC generation flags
-are substituted into the compilation command.
-You can pass compiler and linker specific flags using @samp{-Wc,@var{flag}}
-and @samp{-Xcompiler @var{flag}} or @samp{-Wl,@var{flag}} and
-@samp{-Xlinker @var{flag}}, respectively.
-
-If the @samp{-static} option is given, then a @samp{.o} file is built,
-even if libtool was configured with @samp{--disable-static}.
-
-Note that the @samp{-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
-@example
-libtool gcc -c foo/x.c -o foo/x.lo
-@end example
-will do what you expect.
-
-Note, however, that, if the compiler does not support @samp{-c} and
-@samp{-o}, it is impossible to compile @file{foo/x.c} without
-overwriting an existing @file{./x.o}. Therefore, if you do have a
-source file @file{./x.c}, make sure you introduce dependencies in your
-@file{Makefile} to make sure @file{./x.o} (or @file{./x.lo}) is
-re-created after any sub-directory's @file{x.lo}:
-@example
-x.o x.lo: foo/x.lo bar/x.lo
-@end example
-This will also ensure that make won't try to use a temporarily corrupted
-@file{x.o} to create a program or library. It may cause needless
-recompilation on platforms that support @samp{-c} and @samp{-o}
-together, but it's the only way to make it safe for those that don't.
-
-@node Link mode
-@section Link mode
-@cindex link mode
-@cindex mode, link
-
-@dfn{Link} mode links together object files (including library
-objects) to form another library or to create an executable program.
-
-@var{mode-args} consist of a command using the C compiler to create an
-output file (with the @samp{-o} flag) from several object files.
-
-The following components of @var{mode-args} are treated specially:
-
-@table @samp
-@cindex undefined symbols, allowing
-@cindex unresolved symbols, allowing
-@item -all-static
-If @var{output-file} is a program, then do not link it against any
-shared libraries at all. If @var{output-file} is a library, then only
-create a static library.
-
-@item -avoid-version
-Tries to avoid versioning (@pxref{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.
-
-@item -dlopen @var{file}
-Same as @samp{-dlpreopen @var{file}}, if native dlopening is not
-supported on the host platform (@pxref{Dlopened modules}) or if
-the program is linked with @samp{-static} or @samp{-all-static}.
-Otherwise, no effect. If @var{file} is @code{self} libtool will make
-sure that the program can @code{dlopen} itself, either by enabling
-@code{-export-dynamic} or by falling back to @samp{-dlpreopen self}.
-
-@item -dlpreopen @var{file}
-Link @var{file} into the output program, and add its symbols to
-@var{lt_preloaded_symbols} (@pxref{Dlpreopening}). If @var{file} is
-@code{self}, the symbols of the program itself will be added to
-@var{lt_preloaded_symbols}.
-If @var{file} is @code{force} libtool will make sure that
-@var{lt_preloaded_symbols} is always @emph{defined}, regardless of whether
-it's empty or not.
-
-@item -export-dynamic
-Allow symbols from @var{output-file} to be resolved with @code{dlsym}
-(@pxref{Dlopened modules}).
-
-@item -export-symbols @var{symfile}
-Tells the linker to export only the symbols listed in @var{symfile}.
-The symbol file should end in @samp{.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.
-
-@item -export-symbols-regex @var{regex}
-Same as @samp{-export-symbols}, except that only symbols matching
-the regular expression @var{regex} are exported.
-By default all symbols are exported.
-
-@item -L@var{libdir}
-Search @var{libdir} for required libraries that have already been
-installed.
-
-@item -l@var{name}
-@var{output-file} requires the installed library @file{lib@var{name}}.
-This option is required even when @var{output-file} is not an
-executable.
-
-@item -module
-Creates a library that can be dlopened (@pxref{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.
-
-@item -no-fast-install
-Disable fast-install mode for the executable @var{output-file}
-(@pxref{Invoking ltconfig}). Useful if the program won't be necessarly
-installed.
-
-@item -no-install
-Link an executable @var{output-file} (@pxref{Invoking ltconfig}) that
-can't be installed and therefore doesn't need a wrapper script.
-Useful if the program is only used in the build tree, e.g.,
-for testing or generating other files.
-
-@item -no-undefined
-Declare that @var{output-file} does not depend on any other libraries.
-Some platforms cannot create shared libraries that depend on other
-libraries (@pxref{Inter-library dependencies}).
-
-@item -o @var{output-file}
-Create @var{output-file} from the specified objects and libraries.
-
-@item -release @var{release}
-Specify that the library was generated by release @var{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 @samp{-version-info} flag instead (@pxref{Versioning}).
-
-@item -rpath @var{libdir}
-If @var{output-file} is a library, it will eventually be installed in
-@var{libdir}. If @var{output-file} is a program, add @var{libdir} to
-the run-time path of the program.
-
-@item -R @var{libdir}
-If @var{output-file} is a program, add @var{libdir} to its run-time
-path. If @var{output-file} is a library, add -R@var{libdir} to its
-@var{dependency_libs}, so that, whenever the library is linked into a
-program, @var{libdir} will be added to its run-time path.
-
-@item -static
-If @var{output-file} is a program, then do not link it against any
-uninstalled shared libtool libraries. If @var{output-file} is a
-library, then only create a static library.
-
-@item -version-info @var{current}[:@var{revision}[:@var{age}]]
-If @var{output-file} is a libtool library, use interface version
-information @var{current}, @var{revision}, and @var{age} to build it
-(@pxref{Versioning}). Do @strong{not} use this flag to specify package
-release information, rather see the @samp{-release} flag.
-
-@item -Wl,@var{flag}
-@itemx -Xlinker @var{flag}
-Pass a linker specific flag directly to the linker.
-@end table
-
-If the @var{output-file} ends in @samp{.la}, then a libtool library is
-created, which must be built only from library objects (@samp{.lo} files).
-The @samp{-rpath} option is required. In the current implementation,
-libtool libraries may not depend on other uninstalled libtool libraries
-(@pxref{Inter-library dependencies}).
-
-If the @var{output-file} ends in @samp{.a}, then a standard library is
-created using @code{ar} and possibly @code{ranlib}.
-
-@cindex partial linking
-@cindex linking, partial
-If @var{output-file} ends in @samp{.o} or @samp{.lo}, then a reloadable object
-file is created from the input files (generally using @samp{ld -r}).
-This method is often called @dfn{partial linking}.
-
-Otherwise, an executable program is created.
-
-@node Execute mode
-@section Execute mode
-@cindex execute mode
-@cindex mode, execute
-
-For @dfn{execute} mode, the library path is automatically set, then a
-program is executed.
-
-The first of the @var{mode-args} is treated as a program name, with the
-rest as arguments to that program.
-
-The following components of @var{mode-args} are treated specially:
-
-@table @samp
-@item -dlopen @var{file}
-Add the directory containing @var{file} to the library path.
-@end table
-
-This mode sets the library path environment variable according to any
-@samp{-dlopen} flags.
-
-If any of the @var{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.
-
-@node Install mode
-@section Install mode
-@cindex install mode
-@cindex mode, install
-
-In @dfn{install} mode, libtool interprets @var{mode-args} as an
-installation command beginning with @code{cp}, or a BSD-compatible
-@code{install} program.
-
-The rest of the @var{mode-args} are interpreted as arguments to that
-command.
-
-The command is run, and any necessary unprivileged post-installation
-commands are also completed.
-
-@node Finish mode
-@section Finish mode
-@cindex finish mode
-@cindex mode, finish
-
-@dfn{Finish} mode helps system administrators install libtool libraries
-so that they can be located and linked into user programs.
-
-Each @var{mode-arg} is interpreted as the name of a library directory.
-Running this command may require superuser privileges, so the
-@samp{--dry-run} option may be useful.
-
-@node Uninstall mode
-@section Uninstall mode
-@cindex uninstall mode
-@cindex mode, uninstall
-
-@dfn{Uninstall} mode deletes installed libraries, executables and objects.
-
-The first @var{mode-arg} is the name of the program to use to delete
-files (typically @file{/bin/rm}).
-
-The remaining @var{mode-args} are either flags for the deletion program
-(beginning with a `-'), or the names of files to delete.
-
-@node Clean mode
-@section Clean mode
-@cindex clean mode
-@cindex mode, clean
-
-@dfn{Clean} mode deletes uninstalled libraries, executables, objects
-and libtool's temporary files associated with them.
-
-The first @var{mode-arg} is the name of the program to use to delete
-files (typically @file{/bin/rm}).
-
-The remaining @var{mode-args} are either flags for the deletion program
-(beginning with a `-'), or the names of files to delete.
-
-@node Integrating libtool
-@chapter 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 @file{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.
-@end menu
-
-@node Makefile rules
-@section Writing @file{Makefile} rules for libtool
-@cindex Makefile
-@cindex Makefile.am
-@cindex Makefile.in
-
-Libtool is fully integrated with Automake (@pxref{Top,, Introduction,
-automake, The Automake Manual}), starting with Automake version 1.2.
-
-If you want to use libtool in a regular @file{Makefile} (or
-@file{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:
-
-@enumerate 1
-@item
-Download Automake (version 1.2 or later) from your nearest GNU mirror,
-install it, and start using it.
-
-@item
-Learn how to write @file{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 @file{Makefile.in} in the @file{demo}
-subdirectory of the libtool distribution@dots{} note especially that it
-was automatically generated from the @file{Makefile.am} by Automake).
-@end enumerate
-
-@node Using Automake
-@section Using Automake with libtool
-
-@vindex LTLIBRARIES
-Libtool library support is implemented under the @samp{LTLIBRARIES}
-primary.
-
-Here are some samples from the Automake @file{Makefile.am} in the
-libtool distribution's @file{demo} subdirectory.
-
-First, to link a program against a libtool library, just use the
-@samp{program_LDADD} variable:
-
-@example
-bin_PROGRAMS = hell hell.debug
-
-# Build hell from main.c and libhello.la
-hell_SOURCES = main.c
-hell_LDADD = libhello.la
-
-# Create an easier-to-debug version of hell.
-hell_debug_SOURCES = main.c
-hell_debug_LDADD = libhello.la
-hell_debug_LDFLAGS = -static
-@end example
-
-The flags @samp{-dlopen} or @samp{-dlpreopen} (@pxref{Link mode}) would
-fit better in the @var{program_LDADD} variable. Unfortunately, GNU
-automake, up to release 1.4, doesn't accept these flags in a
-@var{program_LDADD} variable, so you have the following alternatives:
-
-@itemize @bullet
-@item
-add them to @var{program_LDFLAGS}, and list the libraries in
-@var{program_DEPENDENCIES}, then wait for a release of GNU automake that
-accepts these flags where they belong;
-
-@item
-surround the flags between quotes, but then you must set
-@var{program_DEPENDENCIES} too:
-
-@example
-program_LDADD = "-dlopen" libfoo.la
-program_DEPENDENCIES = libfoo.la
-@end example
-
-@item
-set and @samp{AC_SUBST} variables @var{DLOPEN} and @var{DLPREOPEN} in
-@file{configure.in} and use @samp{@@DLOPEN@@} and @samp{@@DLPREOPEN@@}
-as replacements for the explicit flags @samp{-dlopen} and
-@samp{-dlpreopen} in @samp{program_LDADD}. Automake will discard
-@samp{AC_SUBST}ed variables from dependencies, so it will behave exactly
-as we expect it to behave when it accepts these flags in
-@samp{program_LDADD}. But hey!, this is ugly!
-@end itemize
-
-You may use the @samp{program_LDFLAGS} variable to stuff in any flags
-you want to pass to libtool while linking @samp{program} (such as
-@samp{-static} to avoid linking uninstalled shared libtool libraries).
-
-Building a libtool library is almost as trivial@dots{} note the use of
-@samp{libhello_la_LDFLAGS} to pass the @samp{-version-info}
-(@pxref{Versioning}) option to libtool:
-
-@example
-# Build a libtool library, libhello.la for installation in libdir.
-lib_LTLIBRARIES = libhello.la
-libhello_la_SOURCES = hello.c foo.c
-libhello_la_LDFLAGS = -version-info 3:12:1
-@end example
-
-The @samp{-rpath} option is passed automatically by Automake (except for
-libraries listed as @code{noinst_LTLIBRARIES}), so you
-should not specify it.
-
-@xref{A Shared Library, Building a Shared Library, The Automake Manual,
-automake, The Automake Manual}, for more information.
-
-@node Configuring
-@section Configuring libtool
-@cindex configuring libtool
-
-Libtool requires intimate knowledge of your compiler suite and operating
-system in order to be able to create shared libraries and link against
-them properly. When you install the libtool distribution, a
-system-specific libtool script is installed into your binary directory.
-
-However, when you distribute libtool with your own packages
-(@pxref{Distributing}), you do not always know which compiler suite and
-operating system are used to compile your package.
-
-For this reason, libtool must be @dfn{configured} before it can be
-used. This idea should be familiar to anybody who has used a GNU
-@code{configure} script. @code{configure} runs a number of tests for
-system features, then generates the @file{Makefiles} (and possibly a
-@file{config.h} header file), after which you can run @code{make} and
-build the package.
-
-Libtool has its own equivalent to the @code{configure} script,
-@code{ltconfig}.
-
-@menu
-* Invoking ltconfig:: @code{ltconfig} command line options.
-* ltconfig example:: Manually configuring a @code{libtool}.
-* AM_PROG_LIBTOOL:: Configuring @code{libtool} in @file{configure.in}.
-@end menu
-
-@node Invoking ltconfig
-@subsection Invoking @code{ltconfig}
-@pindex ltconfig
-@cindex ltconfig command options
-@cindex options, ltconfig command
-@cindex command options, ltconfig
-
-@code{ltconfig} runs a series of configuration tests, then creates a
-system-specific @code{libtool} in the current directory. The
-@code{ltconfig} program has the following synopsis:
-
-@example
-ltconfig [@var{option}]@dots{} @var{ltmain} [@var{host}]
-@end example
-
-@noindent
-and accepts the following options:
-
-@table @samp
-@item --build=@var{build}
-Set the build system to be different to the host system. This creates a
-libtool which prefers build tools which are prefixed by the host alias over
-the standard tools. For example, specifying @code{--build=i486-pc-linux-gnu}
-on a host described by i486-pc-cygwin would create a libtool which used
-@code{i486-pc-cygwin-ranlib} in preference to @code{ranlib} if present. This
-is useful for cross build environments.
-
-@item --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 @code{less} (or
-@code{more}) or redirect to a file.
-
-@item --disable-shared
-Create a @code{libtool} that only builds static libraries.
-
-@item --disable-static
-Create a @code{libtool} that builds only shared libraries if they are
-available. If only static libraries can be built, then this flag has
-no effect.
-
-@item --disable-fast-install
-On platforms in which installable executables, that are created by
-default, are not suitable for execution in the build directory, create a
-@code{libtool} that links executables that search for uninstalled
-libraries by default, and relinks them at install time. It is ignored
-on platforms in which a single executable is enough.
-
-@item --enable-dlopen
-Test whether some dlopening mechanism is supported. If this flag is not
-given, or no working dlopening mechanism is found, create a
-@code{libtool} that performs dlpreopening of all dlopened modules.
-
-@item --help
-Display a help message and exit.
-
-@item --no-verify
-Do not use @code{config.sub} to verify that @var{host} is a valid
-canonical host system name.
-
-@item --output=@var{file}
-@item -o @var{file}
-Instead of creating a libtool script called @code{libtool}, create one
-called @var{file}. This can be useful if you want to create libtool
-scripts for cross-compilers, or you want to have more than one libtool
-in the same directory.
-
-@item --quiet
-@itemx --silent
-Do not print informational messages when running configuration tests.
-
-@item --srcdir=@var{dir}
-Look for @code{config.guess} and @code{config.sub} in @var{dir}.
-
-@item --version
-Print @code{ltconfig} version information and exit.
-
-@item --add-tag=@var{tag}
-Instead of overwriting @code{libtool}, append a new configuration
-section to it, with the given @var{tag}.
-
-@item --with-gcc
-Assume that the GNU C compiler will be used when invoking the created
-@code{libtool} to compile and link object files.
-
-@item --with-gnu-ld
-Assume that the C compiler uses the GNU linker.
-
-@item --disable-lock
-Create a @code{libtool} that does not perform locking to ensure proper
-parallel compilation if the C compiler does not support @samp{-c} and
-@samp{-o} together.
-
-@item --cache-file=@var{file}
-Use this @var{file} as a cache for results of a few tests. This is
-usually @file{config.cache} used by @code{configure}. By default, no
-cache file is used.
-@end table
-
-@var{ltmain} is the @code{ltmain.sh} shell script fragment that provides
-the basic libtool functionality (@pxref{Distributing}).
-
-@var{host} is the canonical host system name, which by default is
-guessed by running @code{config.guess}.
-
-@code{ltconfig} also recognizes the following environment variables:
-
-@defvar CC
-The compiler that will be used by the generated @code{libtool}. If
-this is not set, @code{ltconfig} will look for @code{gcc} or @code{cc}.
-@end defvar
-
-@defvar LTCC
-A C compiler, in case @var{CC} is not one. If this is not set,
-@code{ltconfig} will use @var{CC} or extract @var{LTCC} from an existing
-@code{libtool}, if running in @samp{--add-tag} mode.
-@end defvar
-
-@defvar CFLAGS
-Compiler flags used to generate standard object files. If this is not
-set, @code{ltconfig} will not use any such flags. It affects only the
-way @code{ltconfig} runs tests, not the produced @code{libtool}.
-@end defvar
-
-@defvar CPPFLAGS
-C preprocessor flags. If this is not set, @code{ltconfig} will not use
-any such flags. It affects only the way @code{ltconfig} runs tests, not
-the produced @code{libtool}.
-@end defvar
-
-@defvar LD
-The system linker to use (if the generated @code{libtool} requires one).
-If this is not set, @code{ltconfig} will try to find out what is the
-linker used by @var{CC}.
-@end defvar
-
-@defvar LDFLAGS
-The flags to be used by @code{ltconfig} when it links a program. If
-this is not set, @code{ltconfig} will not use any such flags. It
-affects only the way @code{ltconfig} runs tests, not the produced
-@code{libtool}.
-@end defvar
-
-@defvar LIBS
-The libraries to be used by @code{ltconfig} when it links a program. If
-this is not set, @code{ltconfig} will not use any such flags. It
-affects only the way @code{ltconfig} runs tests, not the produced
-@code{libtool}.
-@end defvar
-
-@defvar NM
-Program to use rather than checking for @code{nm}.
-@end defvar
-
-@defvar RANLIB
-Program to use rather than checking for @code{ranlib}.
-@end defvar
-
-@defvar LN_S
-A command that creates a link of a program, a soft-link if possible, a
-hard-link otherwise.
-@end defvar
-
-@defvar DLLTOOL
-Program to use rather than checking for @code{dlltool}. Only meaningful
-for Cygwin/MS-Windows.
-@end defvar
-
-@defvar OBJDUMP
-Program to use rather than checking for @code{objdump}. Only meaningful
-for Cygwin/MS-Windows.
-@end defvar
-
-@defvar AS
-Program to use rather than checking for @code{as}. Only meaningful for
-Cygwin/MS-Windows.
-@end defvar
-
-@node ltconfig example
-@subsection Using @code{ltconfig}
-
-Here is a simple example of using @code{ltconfig} to configure libtool
-on a NetBSD/i386 1.2 system:
-
-@example
-burger$ @kbd{./ltconfig ltmain.sh}
-checking host system type... i386-unknown-netbsd1.2
-checking for ranlib... ranlib
-checking for gcc... gcc
-checking whether we are using GNU C... yes
-checking for gcc option to produce PIC... -fPIC -DPIC
-checking for gcc option to statically link programs... -static
-checking if ld is GNU ld... no
-checking if ld supports shared libraries... yes
-checking dynamic linker characteristics... netbsd1.2 ld.so
-checking if libtool supports shared libraries... yes
-checking whether to build shared libraries... yes
-creating libtool
-burger$
-@end example
-
-This example shows how to configure @code{libtool} for cross-compiling
-to a i486 GNU/Hurd 0.1 system (assuming compiler tools reside in
-@file{/local/i486-gnu/bin}):
-
-@example
-burger$ export PATH=/local/i486-gnu/bin:$PATH
-burger$ ./ltconfig ltmain.sh i486-gnu0.1
-checking host system type... i486-unknown-gnu0.1
-checking for ranlib... ranlib
-checking for gcc... gcc
-checking whether we are using GNU C... yes
-checking for gcc option to produce PIC... -fPIC -DPIC
-checking for gcc option to statically link programs... -static
-checking if ld is GNU ld... yes
-checking if GNU ld supports shared libraries... yes
-checking dynamic linker characteristics... gnu0.1 ld.so
-checking if libtool supports shared libraries... yes
-checking whether to build shared libraries... yes
-creating libtool
-burger$
-@end example
-
-@node AM_PROG_LIBTOOL
-@subsection The @code{AM_PROG_LIBTOOL} macro
-
-If you are using GNU Autoconf (or Automake), you should add a call to
-@code{AM_PROG_LIBTOOL} to your @file{configure.in} file. This macro
-offers seamless integration between the @code{configure} script and
-@code{ltconfig}:
-
-@defmac AM_PROG_LIBTOOL
-Add support for the @samp{--enable-shared} and @samp{--disable-shared}
-@code{configure} flags. Invoke @code{ltconfig} with the correct
-arguments to configure the package (@pxref{Invoking
-ltconfig}).@footnote{@code{AM_PROG_LIBTOOL} requires that you define the
-@file{Makefile} variable @code{top_builddir} in your @file{Makefile.in}.
-Automake does this automatically, but Autoconf users should set it to
-the relative path to the top of your build directory (@file{../..}, for
-example).}
-
-By default, this macro turns on shared libraries if they are available,
-and also enables static libraries if they don't conflict with the shared
-libraries. You can modify these defaults by calling either the
-@code{AC_DISABLE_SHARED} or @code{AC_DISABLE_STATIC} macros:
-
-@example
-# Turn off shared libraries during beta-testing, since they
-# make the build process take too long.
-AC_DISABLE_SHARED
-AM_PROG_LIBTOOL
-@end example
-
-The user may specify modified forms of the configure flags
-@samp{--enable-shared} and @samp{--enable-static} to choose whether
-shared or static libraries are built based on the name of the package.
-For example, to have shared @samp{bfd} and @samp{gdb} libraries built,
-but not shared @samp{libg++}, you can run all three @code{configure}
-scripts as follows:
-
-@example
-trick$ ./configure --enable-shared=bfd,gdb
-@end example
-
-In general, specifying @samp{--enable-shared=@var{pkgs}} is the same as
-configuring with @samp{--enable-shared} every package named in the
-comma-separated @var{pkgs} list, and every other package with
-@samp{--disable-shared}. The @samp{--enable-static=@var{pkgs}} flag
-behaves similarly, but it uses @samp{--enable-static} and
-@samp{--disable-static}. The same applies to the
-@samp{--enable-fast-install=@var{pkgs}} flag, which uses
-@samp{--enable-fast-install} and @samp{--disable-fast-install}.
-
-The package name @samp{default} matches any packages which have not set
-their name in the @code{PACKAGE} environment variable.
-
-This macro also sets the shell variable @var{LIBTOOL_DEPS}, that you can
-use to automatically update the libtool script if it becomes
-out-of-date. In order to do that, add to your @file{configure.in}:
-
-@example
-AM_PROG_LIBTOOL
-AC_SUBST(LIBTOOL_DEPS)
-@end example
-
-and, to @file{Makefile.in} or @file{Makefile.am}:
-
-@example
-LIBTOOL_DEPS = @@LIBTOOL_DEPS@@
-libtool: $(LIBTOOL_DEPS)
- $(SHELL) ./config.status --recheck
-@end example
-
-If you are using GNU automake, you can omit the assignment, as automake
-will take care of it. You'll obviously have to create some dependency
-on @file{libtool}.
-
-@end defmac
-
-@defmac AC_LIBTOOL_CXX
-Enable C++ shared library support. This macro should be used if libtool
-will be used to generate C++ shared libraries. It causes a C++-specific
-configuration to be appended to the @file{libtool} script. The C++
-support can coexist with other configurations, including the default C
-shared library configuration. It is not necessary to invoke this macro
-explicitly, as long as @code{AC_PROG_CXX} is called within the configure
-script.
-@end defmac
-
-@defmac AC_LIBTOOL_GCJ
-Enable GCJ shared library support. This macro should be used if libtool
-will be used to generate GCJ shared libraries. It causes a GCJ-specific
-configuration to be appended to the @file{libtool} script. The GCJ
-support can coexist with other configurations, including the default C
-shared library configuration. It is not necessary to invoke this macro
-explicitly, as long as @code{AM_PROG_GCJ} (or @code{AC_PROG_GCJ},
-whenever it is implemented in autoconf) is called within the configure
-script.
-@end defmac
-
-@defmac AC_LIBTOOL_DLOPEN
-Enable checking for dlopen support. This macro should be used if
-the package makes use of the @samp{-dlopen} and @samp{-dlpreopen} flags,
-otherwise libtool will assume that the system does not support dlopening.
-The macro must be called @strong{before} @code{AM_PROG_LIBTOOL}.
-@end defmac
-
-@defmac AC_LIBTOOL_WIN32_DLL
-This macro should be used if the package has been ported to build clean
-dlls on win32 platforms. Usually this means that any library data items
-are exported with @code{__declspec(dllexport)} and imported with
-@code{__declspec(dllimport)}. If this macro is not used, libtool will
-assume that the package libraries are not dll clean and will build only
-static libraries on win32 hosts.
-
-@code{AM_PROG_LIBTOOL} must be called @strong{after} this macro, and
-provision must be made to pass @samp{-no-undefined} to @code{libtool}
-in link mode from the package @code{Makefile}. Naturally, passing
-@samp{-no-undefined} means that all the library symbols @strong{really are}
-defined at link time!
-@end defmac
-
-@defmac AC_DISABLE_FAST_INSTALL
-Change the default behaviour for @code{AM_PROG_LIBTOOL} to disable
-optimization for fast installation. The user may still override this
-default, depending on platform support, by specifying
-@samp{--enable-fast-install}.
-@end defmac
-
-@defmac AC_DISABLE_SHARED
-@defmacx AM_DISABLE_SHARED
-Change the default behaviour for @code{AM_PROG_LIBTOOL} to disable
-shared libraries. The user may still override this default by
-specifying @samp{--enable-shared}.
-@end defmac
-
-@defmac AC_DISABLE_STATIC
-@defmacx AM_DISABLE_STATIC
-Change the default behaviour for @code{AM_PROG_LIBTOOL} to disable
-static libraries. The user may still override this default by
-specifying @samp{--enable-static}.
-@end defmac
-
-@pindex aclocal
-When you invoke the @code{libtoolize} program (@pxref{Invoking
-libtoolize}), it will tell you where to find a definition of
-@code{AM_PROG_LIBTOOL}. If you use Automake, the @code{aclocal} program
-will automatically add @code{AM_PROG_LIBTOOL} support to your
-@code{configure} script.
-
-Nevertheless, it is advisable to include a copy of @file{libtool.m4} in
-@file{acinclude.m4}, so that, even if @file{aclocal.m4} and
-@file{configure} are rebuilt for any reason, the appropriate libtool
-macros will be used. The alternative is to hope the user will have a
-compatible version of @file{libtool.m4} installed and accessible for
-@code{aclocal}. This may lead to weird errors when versions don't
-match.
-
-@node Distributing
-@section Including libtool in your package
-
-In order to use libtool, you need to include the following files with
-your package:
-
-@table @file
-@item config.guess
-@pindex config.guess
-Attempt to guess a canonical system name.
-
-@item config.sub
-@pindex config.sub
-Canonical system name validation subroutine script.
-
-@item ltconfig
-Generate a libtool script for a given system.
-
-@item ltmain.sh
-@pindex ltmain.sh
-A generic script implementing basic libtool functionality.
-@end table
-
-Note that the libtool script itself should @emph{not} be included with
-your package. @xref{Configuring}.
-
-You should use the @code{libtoolize} program, rather than manually
-copying these files into your package.
-
-@menu
-* Invoking libtoolize:: @code{libtoolize} command line options.
-* Autoconf .o macros:: Autoconf macros that set object file names.
-@end menu
-
-@node Invoking libtoolize
-@subsection Invoking @code{libtoolize}
-@pindex libtoolize
-@cindex libtoolize command options
-@cindex command options, libtoolize
-@cindex options, libtoolize command
-
-The @code{libtoolize} program provides a standard way to add libtool
-support to your package. In the future, it may implement better usage
-checking, or other features to make libtool even easier to use.
-
-The @code{libtoolize} program has the following synopsis:
-
-@example
-libtoolize [@var{option}]@dots{}
-@end example
-
-@noindent
-and accepts the following options:
-
-@table @samp
-@item --automake
-Work silently, and assume that Automake libtool support is used.
-
-@samp{libtoolize --automake} is used by Automake to add libtool files to
-your package, when @code{AM_PROG_LIBTOOL} appears in your
-@file{configure.in}.
-
-@item --copy
-@itemx -c
-Copy files from the libtool data directory rather than creating
-symlinks.
-
-@item --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 @code{less} (or
-@code{more}) or redirect to a file.
-
-@item --dry-run
-@itemx -n
-Don't run any commands that modify the file system, just print them
-out.
-
-@item --force
-@itemx -f
-Replace existing libtool files. By default, @code{libtoolize} won't
-overwrite existing files.
-
-@item --help
-Display a help message and exit.
-
-@item --ltdl
-Install libltdl in a subdirectory of your package.
-
-@item --ltdl-tar
-Add the file libltdl.tar.gz to your package.
-
-@item --version
-Print @code{libtoolize} version information and exit.
-@end table
-
-@findex AC_CONFIG_AUX_DIR
-If @code{libtoolize} detects an explicit call to
-@code{AC_CONFIG_AUX_DIR} (@pxref{Input, , The Autoconf Manual,
-autoconf, The Autoconf Manual}) in your @file{configure.in}, it
-will put the files in the specified directory.
-
-@code{libtoolize} displays hints for adding libtool support to your
-package, as well.
-
-@node Autoconf .o macros
-@subsection Autoconf @samp{.o} macros
-
-The Autoconf package comes with a few macros that run tests, then set a
-variable corresponding to the name of an object file. Sometimes it is
-necessary to use corresponding names for libtool objects.
-
-Here are the names of variables that list libtool objects:
-
-@defvar LTALLOCA
-@findex AC_FUNC_ALLOCA
-Substituted by @code{AC_FUNC_ALLOCA} (@pxref{Particular Functions, Particular
-Function Checks, The Autoconf Manual, autoconf, The Autoconf
-Manual}). Is either empty, or contains @samp{alloca.lo}.
-@end defvar
-
-@defvar LTLIBOBJS
-@findex AC_REPLACE_FUNCS
-Substituted by @code{AC_REPLACE_FUNCS} (@pxref{Generic Functions, Generic
-Function Checks, The Autoconf Manual, autoconf, The Autoconf
-Manual}), and a few other functions.
-@end defvar
-
-Unfortunately, the most recent version of Autoconf (2.12, at the time of
-this writing) does not have any way for libtool to provide support for
-these variables. So, if you depend on them, use the following code
-immediately before the call to @code{AC_OUTPUT} in your
-@file{configure.in}:
-
-@example
-LTLIBOBJS=`echo "$LIBOBJS" | sed 's/\.o/.lo/g'`
-AC_SUBST(LTLIBOBJS)
-LTALLOCA=`echo "$ALLOCA" | sed 's/\.o/.lo/g'`
-AC_SUBST(LTALLOCA)
-AC_OUTPUT(@dots{})
-@end example
-
-@node Static-only libraries
-@section Static-only libraries
-@cindex debugging libraries
-@cindex developing libraries
-@cindex double-compilation, avoiding
-@cindex avoiding shared libraries
-@cindex eliding shared libraries
-@cindex using shared libraries, not
-@cindex shared libraries, not using
-@cindex time, saving
-@cindex saving time
-
-When you are developing a package, it is often worthwhile to configure
-your package with the @samp{--disable-shared} flag, or to override the
-defaults for @code{AM_PROG_LIBTOOL} by using the
-@code{AM_DISABLE_SHARED} Autoconf macro (@pxref{AM_PROG_LIBTOOL, , The
-@code{AM_PROG_LIBTOOL} macro}). This prevents libtool from building
-shared libraries, which has several advantages:
-
-@itemize @bullet
-@item
-compilation is twice as fast, which can speed up your development cycle,
-
-@item
-debugging is easier because you don't need to deal with any complexities
-added by shared libraries, and
-
-@item
-you can see how libtool behaves on static-only platforms.
-@end itemize
-
-You may want to put a small note in your package @file{README} to let
-other developers know that @samp{--disable-shared} can save them time.
-The following example note is taken from the GIMP@footnote{GNU Image
-Manipulation Program, for those who haven't taken the plunge. See
-@url{http://www.gimp.org/}.} distribution @file{README}:
-
-@example
-The GIMP uses GNU Libtool in order to build shared libraries on a
-variety of systems. While this is very nice for making usable
-binaries, it can be a pain when trying to debug a program. For that
-reason, compilation of shared libraries can be turned off by
-specifying the @samp{--disable-shared} option to @file{configure}.
-@end example
-
-@node Versioning
-@chapter Library interface versions
-@cindex dynamic dependencies
-@cindex dependency versioning
-@cindex shared library versions
-
-The most difficult issue introduced by shared libraries is that of
-creating and resolving runtime dependencies. Dependencies on programs
-and libraries are often described in terms of a single name, such as
-@code{sed}. So, one may say ``libtool depends on sed,'' and that is
-good enough for most purposes.
-
-However, when an interface changes regularly, we need to be more
-specific: ``Gnus 5.1 requires Emacs 19.28 or above.'' Here, the
-description of an interface consists of a name, and a ``version
-number.''
-
-Even that sort of description is not accurate enough for some purposes.
-What if Emacs 20 changes enough to break Gnus 5.1?
-
-The same problem exists in shared libraries: we require a formal version
-system to describe the sorts of dependencies that programs have on
-shared libraries, so that the dynamic linker can guarantee that programs
-are linked only against libraries that provide the interface they
-require.
-
-@menu
-* 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.
-@end menu
-
-@node Interfaces
-@section What are library interfaces?
-@cindex library interfaces
-
-Interfaces for libraries may be any of the following (and more):
-
-@itemize @bullet
-@item
-global variables: both names and types
-
-@item
-global functions: argument types and number, return types, and function names
-
-@item
-standard input, standard output, standard error, and file formats
-
-@item
-sockets, pipes, and other inter-process communication protocol formats
-@end itemize
-
-Note that static functions do not count as interfaces, because they are
-not directly available to the user of the library.
-
-@node Libtool versioning
-@section Libtool's versioning system
-@cindex libtool library versions
-@cindex formal versioning
-@cindex versioning, formal
-
-Libtool has its own formal versioning system. It is not as flexible as
-some, but it is definitely the simplest of the more powerful versioning
-systems.
-
-Think of a library as exporting several sets of interfaces, arbitrarily
-represented by integers. When a program is linked against a library, it
-may use any subset of those interfaces.
-
-Libtool's description of the interfaces that a program uses is simple:
-it encodes the least and the greatest interface numbers in the resulting
-binary (@var{first-interface}, @var{last-interface}).
-
-The dynamic linker is guaranteed that if a library supports @emph{every}
-interface number between @var{first-interface} and @var{last-interface},
-then the program can be relinked against that library.
-
-Note that this can cause problems because libtool's compatibility
-requirements are actually stricter than is necessary.
-
-Say @file{libhello} supports interfaces 5, 16, 17, 18, and 19, and that
-libtool is used to link @file{test} against @file{libhello}.
-
-Libtool encodes the numbers 5 and 19 in @file{test}, and the dynamic
-linker will only link @file{test} against libraries that support
-@emph{every} interface between 5 and 19. So, the dynamic linker refuses
-to link @file{test} against @file{libhello}!
-
-In order to eliminate this problem, libtool only allows libraries to
-declare consecutive interface numbers. So, @file{libhello} can declare at
-most that it supports interfaces 16 through 19. Then, the dynamic
-linker will link @file{test} against @file{libhello}.
-
-So, libtool library versions are described by three integers:
-
-@table @var
-@item current
-The most recent interface number that this library implements.
-
-@item revision
-The implementation number of the @var{current} interface.
-
-@item age
-The difference between the newest and oldest interfaces that this
-library implements. In other words, the library implements all the
-interface numbers in the range from number @code{@var{current} -
-@var{age}} to @code{@var{current}}.
-@end table
-
-If two libraries have identical @var{current} and @var{age} numbers,
-then the dynamic linker chooses the library with the greater
-@var{revision} number.
-
-@node Updating version info
-@section Updating library version information
-
-If you want to use libtool's versioning system, then you must specify
-the version information to libtool using the @samp{-version-info} flag
-during link mode (@pxref{Link mode}).
-
-This flag accepts an argument of the form
-@samp{@var{current}[:@var{revision}[:@var{age}]]}. So, passing
-@samp{-version-info 3:12:1} sets @var{current} to 3, @var{revision} to
-12, and @var{age} to 1.
-
-If either @var{revision} or @var{age} are omitted, they default to 0.
-Also note that @var{age} must be less than or equal to the @var{current}
-interface number.
-
-Here are a set of rules to help you update your library version
-information:
-
-@enumerate 1
-@item
-Start with version information of @samp{0:0:0} for each libtool library.
-
-@item
-Update the version information only immediately before a public release
-of your software. More frequent updates are unnecessary, and only
-guarantee that the current interface number gets larger faster.
-
-@item
-If the library source code has changed at all since the last update,
-then increment @var{revision} (@samp{@var{c}:@var{r}:@var{a}} becomes
-@samp{@var{c}:@math{r+1}:@var{a}}).
-
-@item
-If any interfaces have been added, removed, or changed since the last
-update, increment @var{current}, and set @var{revision} to 0.
-
-@item
-If any interfaces have been added since the last public release, then
-increment @var{age}.
-
-@item
-If any interfaces have been removed since the last public release, then
-set @var{age} to 0.
-@end enumerate
-
-@strong{@emph{Never}} try to set the interface numbers so that they
-correspond to the release number of your package. This is an abuse that
-only fosters misunderstanding of the purpose of library versions.
-Instead, use the @samp{-release} flag (@pxref{Release numbers}), but be
-warned that every release of your package will not be binary compatible
-with any other release.
-
-@node Release numbers
-@section Managing release information
-
-Often, people want to encode the name of the package release into the
-shared library so that it is obvious to the user which package their
-programs are linked against. This convention is used especially on
-GNU/Linux:
-
-@example
-trick$ @kbd{ls /usr/lib/libbfd*}
-/usr/lib/libbfd.a /usr/lib/libbfd.so.2.7.0.2
-/usr/lib/libbfd.so
-trick$
-@end example
-
-On @samp{trick}, @file{/usr/lib/libbfd.so} is a symbolic link to
-@file{libbfd.so.2.7.0.2}, which was distributed as a part of
-@samp{binutils-2.7.0.2}.
-
-Unfortunately, this convention conflicts directly with libtool's idea of
-library interface versions, because the library interface rarely changes
-at the same time that the release number does, and the library suffix is
-never the same across all platforms.
-
-So, in order to accommodate both views, you can use the @samp{-release}
-flag in order to set release information for libraries which you do not
-want to use @samp{-version-info}. For the @file{libbfd} example, the
-next release which uses libtool should be built with @samp{-release
-2.9.0}, which will produce the following files on GNU/Linux:
-
-@example
-trick$ @kbd{ls /usr/lib/libbfd*}
-/usr/lib/libbfd-2.9.0.so /usr/lib/libbfd.a
-/usr/lib/libbfd.so
-trick$
-@end example
-
-In this case, @file{/usr/lib/libbfd.so} is a symbolic link to
-@file{libbfd-2.9.0.so}. This makes it obvious that the user is dealing
-with @samp{binutils-2.9.0}, without compromising libtool's idea of
-interface versions.
-
-Note that this option causes a modification of the library name, so do
-not use it unless you want to break binary compatibility with any past
-library releases. In general, you should only use @samp{-release} for
-package-internal libraries or for ones whose interfaces change very
-frequently.
-
-@node Library tips
-@chapter Tips for interface design
-@cindex library interfaces, design
-@cindex design of library interfaces
-
-Writing a good library interface takes a lot of practice and thorough
-understanding of the problem that the library is intended to solve.
-
-If you design a good interface, it won't have to change often, you won't
-have to keep updating documentation, and users won't have to keep
-relearning how to use the library.
-
-Here is a brief list of tips for library interface design, which may
-help you in your exploits:
-
-@table @asis
-@item Plan ahead
-Try to make every interface truly minimal, so that you won't need to
-delete entry points very often.
-
-@item Avoid interface changes
-@cindex renaming interface functions
-Some people love redesigning and changing entry points just for the heck
-of it (note: @emph{renaming} a function is considered changing an entry
-point). Don't be one of those people. If you must redesign an
-interface, then try to leave compatibility functions behind so that
-users don't need to rewrite their existing code.
-
-@item Use opaque data types
-@cindex opaque data types
-The fewer data type definitions a library user has access to, the
-better. If possible, design your functions to accept a generic pointer
-(which you can cast to an internal data type), and provide access
-functions rather than allowing the library user to directly manipulate
-the data.
-That way, you have the freedom to change the data structures without
-changing the interface.
-
-This is essentially the same thing as using abstract data types and
-inheritance in an object-oriented system.
-
-@item Use header files
-@cindex header files
-If you are careful to document each of your library's global functions
-and variables in header files, and include them in your library source
-files, then the compiler will let you know if you make any interface
-changes by accident (@pxref{C header files}).
-
-@item Use the @code{static} keyword (or equivalent) whenever possible
-@cindex global functions
-The fewer global functions your library has, the more flexibility you'll
-have in changing them. Static functions and variables may change forms
-as often as you like@dots{} your users cannot access them, so they
-aren't interface changes.
-@end table
-
-@menu
-* C header files:: How to write portable include files.
-@end menu
-
-@node C header files
-@section Writing C header files
-@cindex portable C headers
-@cindex C header files, portable
-@cindex include files, portable
-
-Writing portable C header files can be difficult, since they may be read
-by different types of compilers:
-
-@table @asis
-@item C++ compilers
-C++ compilers require that functions be declared with full prototypes,
-since C++ is more strongly typed than C. C functions and variables also
-need to be declared with the @code{extern "C"} directive, so that the
-names aren't mangled. @xref{C++ libraries}, for other issues relevant
-to using C++ with libtool.
-
-@item ANSI C compilers
-ANSI C compilers are not as strict as C++ compilers, but functions
-should be prototyped to avoid unnecessary warnings when the header file
-is @code{#include}d.
-
-@item non-ANSI C compilers
-Non-ANSI compilers will report errors if functions are prototyped.
-@end table
-
-These complications mean that your library interface headers must use
-some C preprocessor magic in order to be usable by each of the above
-compilers.
-
-@file{foo.h} in the @file{demo} subdirectory of the libtool distribution
-serves as an example for how to write a header file that can be
-safely installed in a system directory.
-
-Here are the relevant portions of that file:
-
-@example
-/* __BEGIN_DECLS should be used at the beginning of your declarations,
- so that C++ compilers don't mangle their names. Use __END_DECLS at
- the end of C declarations. */
-#undef __BEGIN_DECLS
-#undef __END_DECLS
-#ifdef __cplusplus
-# define __BEGIN_DECLS extern "C" @{
-# define __END_DECLS @}
-#else
-# define __BEGIN_DECLS /* empty */
-# define __END_DECLS /* empty */
-#endif
-
-/* __P is a macro used to wrap function prototypes, so that compilers
- that don't understand ANSI C prototypes still work, and ANSI C
- compilers can issue warnings about type mismatches. */
-#undef __P
-#if defined (__STDC__) || defined (_AIX) \
- || (defined (__mips) && defined (_SYSTYPE_SVR4)) \
- || defined(WIN32) || defined(__cplusplus)
-# define __P(protos) protos
-#else
-# define __P(protos) ()
-#endif
-@end example
-
-These macros are used in @file{foo.h} as follows:
-
-@example
-#ifndef _FOO_H_
-#define _FOO_H_ 1
-
-/* The above macro definitions. */
-@dots{}
-
-__BEGIN_DECLS
-int foo __P((void));
-int hello __P((void));
-__END_DECLS
-
-#endif /* !_FOO_H_ */
-@end example
-
-Note that the @file{#ifndef _FOO_H_} prevents the body of @file{foo.h}
-from being read more than once in a given compilation.
-
-Feel free to copy the definitions of @code{__P}, @code{__BEGIN_DECLS},
-and @code{__END_DECLS} into your own headers. Then, you may use them to
-create header files that are valid for C++, ANSI, and non-ANSI
-compilers.
-
-Do not be naive about writing portable code. Following the tips given
-above will help you miss the most obvious problems, but there are
-definitely other subtle portability issues. You may need to cope with
-some of the following issues:
-
-@itemize @bullet
-@item
-Pre-ANSI compilers do not always support the @code{void *} generic
-pointer type, and so need to use @code{char *} in its place.
-
-@item
-The @code{const} and @code{signed} keywords are not supported by some
-compilers, especially pre-ANSI compilers.
-
-@item
-The @code{long double} type is not supported by many compilers.
-@end itemize
-
-@node Inter-library dependencies
-@chapter Inter-library dependencies
-@cindex dependencies between libraries
-@cindex inter-library dependencies
-
-By definition, every shared library system provides a way for
-executables to depend on libraries, so that symbol resolution is
-deferred until runtime.
-
-An @dfn{inter-library dependency} is one in which a library depends on
-other libraries. For example, if the libtool library @file{libhello}
-uses the @code{cos} function, then it has an inter-library dependency
-on @file{libm}, the math library that implements @code{cos}.
-
-Some shared library systems provide this feature in an
-internally-consistent way: these systems allow chains of dependencies of
-potentially infinite length.
-
-However, most shared library systems are restricted in that they only
-allow a single level of dependencies. In these systems, programs may
-depend on shared libraries, but shared libraries may not depend on other
-shared libraries.
-
-In any event, libtool provides a simple mechanism for you to declare
-inter-library dependencies: for every library @file{lib@var{name}} that
-your own library depends on, simply add a corresponding
-@code{-l@var{name}} option to the link line when you create your
-library. To make an example of our
-@file{libhello} that depends on @file{libm}:
-
-@example
-burger$ @kbd{libtool gcc -g -O -o libhello.la foo.lo hello.lo \
- -rpath /usr/local/lib -lm}
-burger$
-@end example
-
-When you link a program against @file{libhello}, you don't need to
-specify the same @samp{-l} options again: libtool will do that for you,
-in order to guarantee that all the required libraries are found. This
-restriction is only necessary to preserve compatibility with static
-library systems and simple dynamic library systems.
-
-Some platforms, such as AIX, do not even allow you this
-flexibility. In order to build a shared library, it must be entirely
-self-contained (that is, have references only to symbols that are found
-in the @samp{.lo} files or the specified @samp{-l} libraries), and you
-need to specify the @var{-no-undefined} flag. By default, libtool
-builds only static libraries on these kinds of platforms.
-
-The simple-minded inter-library dependency tracking code of libtool
-releases prior to 1.2 was disabled because it was not clear when it was
-possible to link one library with another, and complex failures would
-occur. A more complex implementation of this concept was re-introduced
-before release 1.3, but it has not been ported to all platforms that
-libtool supports. The default, conservative behavior is to avoid
-linking one library with another, introducing their inter-dependencies
-only when a program is linked with them.
-
-@node Dlopened modules
-@chapter Dlopened modules
-@findex dlopen
-@findex dlsym
-@findex dlclose
-@findex shl_load
-@cindex dynamic linking, applications
-@cindex dlopening modules
-@cindex modules, dynamic
-@cindex application-level dynamic linking
-
-It can sometimes be confusing to discuss @dfn{dynamic linking}, because
-the term is used to refer to two different concepts:
-
-@enumerate 1
-@item
-Compiling and linking a program against a shared library, which is
-resolved automatically at run time by the dynamic linker. In this
-process, dynamic linking is transparent to the application.
-
-@item
-The application calling functions such as @code{dlopen},@footnote{HP-UX,
-to be different, uses a function named @code{shl_load}.} which load
-arbitrary, user-specified modules at runtime. This type of dynamic
-linking is explicitly controlled by the application.
-@end enumerate
-
-To mitigate confusion, this manual refers to the second type of dynamic
-linking as @dfn{dlopening} a module.
-
-The main benefit to dlopening object modules is the ability to access
-compiled object code to extend your program, rather than using an
-interpreted language. In fact, dlopen calls are frequently used in
-language interpreters to provide an efficient way to extend the
-language.
-
-As of version @value{VERSION}, libtool provides support for dlopened
-modules. However, you should indicate that your package is willing to
-use such support, by using the macro @samp{AC_LIBTOOL_DLOPEN} in
-@file{configure.in}. If this macro is not used (or it is used
-@emph{after} @samp{AM_PROG_LIBTOOL}), libtool will assume no dlopening
-mechanism is available, and will try to simulate it.
-
-This chapter discusses how you as a dlopen application developer might
-use libtool to generate dlopen-accessible modules.
-
-@menu
-* Building modules:: Creating dlopenable objects and libraries.
-* Dlpreopening:: Dlopening that works on static platforms.
-* Finding the dlname:: Choosing the right file to @code{dlopen}.
-* Dlopen issues:: Unresolved problems that need your attention.
-@end menu
-
-@node Building modules
-@section Building modules to dlopen
-
-On some operating systems, a program symbol must be specially declared
-in order to be dynamically resolved with the @code{dlsym} (or
-equivalent) function.
-
-Libtool provides the @samp{-export-dynamic} and @samp{-module}
-link flags (@pxref{Link mode}), which do this declaration.
-You need to use these flags if you are linking an application program that
-dlopens other modules or a libtool library that will also be dlopened.
-
-For example, if we wanted to build a shared library, @file{libhello},
-that would later be dlopened by an application, we would add
-@samp{-module} to the other link flags:
-
-@example
-burger$ @kbd{libtool gcc -module -o libhello.la foo.lo \
- hello.lo -rpath /usr/local/lib -lm}
-burger$
-@end example
-
-If symbols from your @emph{executable} are needed to satisfy unresolved
-references in a library you want to dlopen you will have to use the flag
-@samp{-export-dynamic}.
-You should use @samp{-export-dynamic} while linking the executable that calls
-dlopen:
-
-@example
-burger$ @kbd{libtool gcc -export-dynamic -o hell-dlopener main.o}
-burger$
-@end example
-
-@node Dlpreopening
-@section Dlpreopening
-
-Libtool provides special support for dlopening libtool object and
-libtool library files, so that their symbols can be resolved @emph{even
-on platforms without any @code{dlopen} and @code{dlsym}
-functions}.
-
-Consider the following alternative ways of loading code into your
-program, in order of increasing ``laziness'':
-
-@enumerate 1
-@item
-Linking against object files that become part of the program executable,
-whether or not they are referenced. If an object file cannot be found,
-then the linker refuses to create the executable.
-
-@item
-Declaring a static library to the linker, so that it is searched at link
-time in order to satisfy any undefined references in the above object
-files. If the static library cannot be found, then the linker refuses
-to link the executable.
-
-@item
-Declaring a shared library to the runtime linker, so that it is searched
-at runtime in order to satisfy any undefined references in the above
-files. If the shared library cannot be found, then the dynamic linker
-aborts the program before it runs.
-
-@item
-Dlopening a module, so that the application can resolve its own,
-dynamically-computed references. If there is an error opening the
-module, or the module is not found, then the application can recover
-without crashing.
-@end enumerate
-
-Libtool emulates @samp{-dlopen} on static platforms by linking objects
-into the program at compile time, and creating data structures that
-represent the program's symbol table.
-
-In order to use this feature, you must declare the objects you want your
-application to dlopen by using the @samp{-dlopen} or @samp{-dlpreopen}
-flags when you link your program (@pxref{Link mode}).
-
-@deftypefn {Structure} {struct} lt_dlsymlist @{ @w{const char *@var{name};} @w{lt_ptr_t @var{address};} @}
-The @var{name} attribute is a null-terminated character string of the
-symbol name, such as @code{"fprintf"}. The @var{address} attribute is a
-generic pointer to the appropriate object, such as @code{&fprintf}.
-@end deftypefn
-
-@deftypevar {const lt_dlsymlist *} lt_preloaded_symbols
-An array of @var{lt_symbol} structures, representing all the preloaded
-symbols linked into the program. For each @samp{-dlpreloaded} file
-there is an element with the @var{name} of the file and a @var{address}
-of @code{0}, followed by all symbols exported from this file.
-For the executable itself the special name @@PROGRAM@@ is used.
-The last element has a @var{name} and @var{address} of @code{0}.
-@end deftypevar
-
-Some compilers may allow identifiers which are not valid in ANSI C, such
-as dollar signs. Libtool only recognizes valid ANSI C symbols (an
-initial ASCII letter or underscore, followed by zero or more ASCII
-letters, digits, and underscores), so non-ANSI symbols will not appear
-in @var{lt_preloaded_symbols}.
-
-@node Finding the dlname
-@section Finding the correct name to dlopen
-@cindex names of dynamic modules
-@cindex dynamic modules, names
-
-After a library has been linked with @samp{-module}, it can be dlopened.
-Unfortunately, because of the variation in library names,
-your package needs to determine the correct file to dlopen.
-
-The most straightforward and flexible implementation is to determine the
-name at runtime, by finding the installed @samp{.la} file, and searching
-it for the following lines:
-
-@example
-# The name that we can @code{dlopen}.
-dlname='@var{dlname}'
-@end example
-
-If @var{dlname} is empty, then the library cannot be dlopened.
-Otherwise, it gives the dlname of the library. So, if the library was
-installed as @file{/usr/local/lib/libhello.la}, and the @var{dlname} was
-@file{libhello.so.3}, then @file{/usr/local/lib/libhello.so.3} should be
-dlopened.
-
-If your program uses this approach, then it should search the
-directories listed in the @code{LD_LIBRARY_PATH}@footnote{@code{LIBPATH}
-on AIX, and @code{SHLIB_PATH} on HP-UX.} environment variable, as well as
-the directory where libraries will eventually be installed. Searching
-this variable (or equivalent) will guarantee that your program can find
-its dlopened modules, even before installation, provided you have linked
-them using libtool.
-
-@node Dlopen issues
-@section Unresolved dlopen issues
-@cindex pitfalls with dlopen
-@cindex dlopening, pitfalls
-@cindex trouble with dlopen
-
-The following problems are not solved by using libtool's dlopen support:
-
-@itemize @bullet
-@item
-Dlopen functions are generally only available on shared library
-platforms. If you want your package to be portable to static platforms,
-you have to use either libltdl (@pxref{Using libltdl}) or develop your
-own alternatives to dlopening dynamic code.
-Most reasonable solutions involve writing wrapper functions for the
-@code{dlopen} family, which do package-specific tricks when dlopening
-is unsupported or not available on a given platform.
-
-@item
-There are major differences in implementations of the @code{dlopen}
-family of functions. Some platforms do not even use the same function
-names (notably HP-UX, with its @code{shl_load} family).
-
-@item
-The application developer must write a custom search function in order
-to discover the correct module filename to supply to @code{dlopen}.
-@end itemize
-
-@node Using libltdl
-@chapter Using libltdl
-@findex libltdl
-@findex dlopen
-@findex dlsym
-@findex dlclose
-@findex dlerror
-@findex shl_load
-@cindex dynamic linking, applications
-@cindex dlopening modules
-@cindex modules, dynamic
-@cindex application-level dynamic linking
-
-Libtool provides a small library, called @file{libltdl}, that aims at
-hiding the various difficulties of dlopening libraries from programmers.
-It consists of a header-file and a small C source file that can be
-distributed with applications that need dlopening functionality. On
-some platforms, whose dynamic linkers are too limited for a simple
-implementation of @file{libltdl} services, it requires GNU DLD, or it
-will only emulate dynamic linking with libtool's dlpreopening mechanism.
-
-@noindent
-libltdl supports currently the following dynamic linking mechanisms:
-
-@itemize @bullet
-@item
-@code{dlopen} (Solaris, Linux and various BSD flavors)
-@item
-@code{shl_load} (HP-UX)
-@item
-@code{LoadLibrary} (Win16 and Win32)
-@item
-@code{load_add_on} (BeOS)
-@item
-GNU DLD (emulates dynamic linking for static libraries)
-@item
-libtool's dlpreopen (see @pxref{Dlpreopening})
-@end itemize
-
-@noindent
-libltdl is licensed under the terms of the GNU Library General Public License,
-with the following exception:
-
-@quotation
-As a special exception to the GNU Library General Public License,
-if you distribute this file as part of a program that uses GNU libtool
-to create libraries and programs, you may include it under the same
-distribution terms that you use for the rest of that program.
-@end quotation
-
-@menu
-* Libltdl interface:: How to use libltdl in your programs.
-* Modules for libltdl:: Creating modules that can be @code{dlopen}ed.
-* Distributing libltdl:: How to distribute libltdl with your package.
-* Module loaders for libltdl:: Creating user defined module loaders.
-@end menu
-
-@node Libltdl interface
-@section How to use libltdl in your programs
-
-@noindent
-The libltdl API is similar to the dlopen interface of Solaris and Linux,
-which is very simple but powerful.
-
-@noindent
-To use libltdl in your program you have to include the header file @file{ltdl.h}:
-
-@example
-#include <ltdl.h>
-@end example
-
-@noindent
-Note that libltdl is not threadsafe, i.e. a multithreaded application
-has to use a mutex for libltdl. It was reported that GNU/Linux's glibc
-2.0's @code{dlopen} with @samp{RTLD_LAZY} (which libltdl uses by
-default) is not thread-safe, but this problem is supposed to be fixed in
-glibc 2.1. On the other hand, @samp{RTLD_NOW} was reported to introduce
-problems in multi-threaded applications on FreeBSD. Working around
-these problems is left as an exercise for the reader; contributions are
-certainly welcome.
-
-@noindent
-The following types are defined in @file{ltdl.h}:
-
-@deftp {Type} lt_ptr_t
-@code{lt_ptr_t} is a generic pointer.
-@end deftp
-
-@deftp {Type} lt_dlhandle
-@code{lt_dlhandle} is a module "handle".
-Every lt_dlopened module has a handle associated with it.
-@end deftp
-
-@deftypefn {Type} {struct} lt_dlinfo @{ @w{char *@var{filename};} @w{char *@var{name};} @w{int @var{ref_count};} @}
-@code{lt_dlinfo} is used to store information about a module.
-The @var{filename} attribute is a null-terminated character string of the
-real module file name. If the module is a libtool module then @var{name}
-is its module name (e.g. @code{"libfoo"} for @code{"dir/libfoo.la"}),
-otherwise it is set to @code{NULL}.
-The @var{ref_count} attribute is a reference counter that describes how often
-the same module is currently loaded.
-@end deftypefn
-
-@deftp {Type} lt_dlsymlist
-@code{lt_dlsymlist} is a symbol list for dlpreopened modules.
-This structure is described in @pxref{Dlpreopening}.
-@end deftp
-
-@page
-@noindent
-libltdl provides the following functions:
-
-@deftypefun int lt_dlinit (void)
-Initialize libltdl.
-This function must be called before using libltdl
-and may be called several times.
-Return 0 on success, otherwise the number of errors.
-@end deftypefun
-
-@deftypefun int lt_dlexit (void)
-Shut down libltdl and close all modules.
-This function will only then shut down libltdl when it was called as
-many times as @code{lt_dlinit} has been successfully called.
-Return 0 on success, otherwise the number of errors.
-@end deftypefun
-
-@deftypefun lt_dlhandle lt_dlopen (const char *@var{filename})
-Open the module with the file name @var{filename} and return a
-handle for it. @code{lt_dlopen} is able to open libtool dynamic
-modules, preloaded static modules, the program itself and
-native dynamic libraries.
-
-Unresolved symbols in the module are resolved using its dependency
-libraries (not implemented yet) and previously dlopened modules. If the
-executable using this module was linked with the @code{-export-dynamic}
-flag, then the global symbols in the executable will also be used to
-resolve references in the module.
-
-If @var{filename} is @code{NULL} and the program was linked with
-@code{-export-dynamic} or @code{-dlopen self}, @code{lt_dlopen} will
-return a handle for the program itself, which can be used to access its
-symbols.
-
-If libltdl cannot find the library and the file name @var{filename} does
-not have a directory component it will additionally search in the
-following search paths for the module (in the order as follows):
-
-@enumerate 1
-@item user-defined search path:
-This search path can be set by the program using the
-functions @code{lt_dlsetsearchpath} and @code{lt_dladdsearchdir}.
-
-@item libltdl's search path:
-This search path is the value of the environment variable
-@var{LTDL_LIBRARY_PATH}.
-
-@item system library search path:
-The system dependent library search path
-(e.g. on Linux it is @var{LD_LIBRARY_PATH}).
-@end enumerate
-
-Each search path must be a colon-separated list of absolute directories,
-for example, @code{"/usr/lib/mypkg:/lib/foo"}.
-
-If the same module is loaded several times, the same handle is returned.
-If @code{lt_dlopen} fails for any reason, it returns @code{NULL}.
-@end deftypefun
-
-@deftypefun lt_dlhandle lt_dlopenext (const char *@var{filename})
-The same as @code{lt_dlopen}, except that it tries to append
-different file name extensions to the file name.
-If the file with the file name @var{filename} cannot be found
-libltdl tries to append the following extensions:
-
-@enumerate 1
-@item the libtool archive extension @samp{.la}
-@item the extension used for native dynamic libraries on the host platform,
-e.g., @samp{.so}, @samp{.sl}, etc.
-@end enumerate
-
-This lookup strategy was designed to allow programs that don't
-have knowledge about native dynamic libraries naming conventions
-to be able to @code{dlopen} such libraries as well as libtool modules
-transparently.
-@end deftypefun
-
-@deftypefun int lt_dlclose (lt_dlhandle @var{handle})
-Decrement the reference count on the module @var{handle}.
-If it drops to zero and no other module depends on this module,
-then the module is unloaded.
-Return 0 on success.
-@end deftypefun
-
-@deftypefun lt_ptr_t lt_dlsym (lt_dlhandle @var{handle}, const char *@var{name})
-Return the address in the module @var{handle}, where the symbol given
-by the null terminated string @var{name} is loaded.
-If the symbol cannot be found, @code{NULL} is returned.
-@end deftypefun
-
-@deftypefun {const char *} lt_dlerror (void)
-Return a human readable string describing the most
-recent error that occurred from any of libltdl's functions.
-Return @code{NULL} if no errors have occurred since initialization
-or since it was last called.
-@end deftypefun
-
-@deftypefun int lt_dlpreload (const lt_dlsymlist *@var{preloaded})
-Register the list of preloaded modules @var{preloaded}.
-If @var{preloaded} is @code{NULL}, then all previously registered
-symbol lists, except the list set by @code{lt_dlpreload_default},
-are deleted. Return 0 on success.
-@end deftypefun
-
-@deftypefun int lt_dlpreload_default (const lt_dlsymlist *@var{preloaded})
-Set the default list of preloaded modules to @var{preloaded}, which
-won't be deleted by @code{lt_dlpreload}. Note that this function does
-@emph{not} require libltdl to be initialized using @code{lt_dlinit} and
-can be used in the program to register the default preloaded modules.
-Instead of calling this function directly, most programs will use the
-macro @code{LTDL_SET_PRELOADED_SYMBOLS}.
-
-Return 0 on success.
-@end deftypefun
-
-@defmac LTDL_SET_PRELOADED_SYMBOLS()
-Set the default list of preloaded symbols.
-Should be used in your program to initialize libltdl's
-list of preloaded modules.
-
-@example
-#include <ltdl.h>
-
-int main() @{
- /* ... */
- LTDL_SET_PRELOADED_SYMBOLS();
- /* ... */
-@}
-@end example
-@end defmac
-
-@deftypefun int lt_dladdsearchdir (const char *@var{search_dir})
-Add the search directory @var{search_dir} to the user-defined library
-search path. Return 0 on success.
-@end deftypefun
-
-@deftypefun int lt_dlsetsearchpath (const char *@var{search_path})
-Replace the current user-defined library search path with
-@var{search_path}, which must be a colon-separated list of absolute
-directories. Return 0 on success.
-@end deftypefun
-
-@deftypefun {const char *} lt_dlgetsearchpath (void)
-Return the current user-defined library search path.
-@end deftypefun
-
-@deftypefun {const lt_dlinfo *} lt_dlgetinfo (lt_dlhandle @var{handle})
-Return a pointer to a struct that contains some information about
-the module @var{handle}. The contents of the struct must not be modified.
-Return @code{NULL} on failure.
-@end deftypefun
-
-@deftypefun int lt_dlforeach (int (*@var{func})(lt_dlhandle @var{handle}, lt_ptr_t @var{data}), lt_ptr_t @var{data})
-For each loaded module call the function @var{func}. The argument
-@var{handle} is the handle of one of the loaded modules, @var{data} is
-the @var{data} argument passed to @code{lt_dlforeach}.
-As soon as @var{func} returns a non-zero value for one of the handles,
-@code{lt_dlforeach} will stop calling @var{func} and immediately return 1.
-Otherwise 0 is returned.
-@end deftypefun
-
-@deftypevar {lt_ptr_t (*} lt_dlmalloc ) (size_t @var{size})
-@deftypevarx {void (*} lt_dlfree ) (lt_ptr_t @var{ptr})
-These variables are set to @code{malloc} and @code{free}, by default,
-but you can set them to any other functions that provides equivalent
-functionality. However, you must not modify their values after calling
-any libltdl function other than @code{lt_dlpreopen_default} or the macro
-@code{LTDL_SET_PRELOADED_SYMBOLS}.
-@end deftypevar
-
-@node Modules for libltdl
-@section Creating modules that can be @code{dlopen}ed
-
-Libtool modules are like normal libtool libraries with a few exceptions:
-
-You have to link the module with libtool's @samp{-module} switch,
-and you should link any program that is intended to dlopen the module with
-@samp{-dlopen modulename.la} so that libtool can dlpreopen the module
-on platforms which don't support dlopening. If the module depends on any
-other libraries, make sure you specify them either when you link the module
-or when you link programs that dlopen it.
-If you want to disable @pxref{Versioning} for a specific module
-you should link it with the @samp{-avoid-version} switch.
-Note that libtool modules don't need to have a "lib" prefix.
-However, automake 1.4 or higher is required to build such modules.
-
-Usually a set of modules provide the same interface, i.e, exports the same
-symbols, so that a program can dlopen them without having to know more
-about their internals.
-In order to avoid symbol conflicts all exported symbols must be prefixed
-with "modulename_LTX_" (@samp{modulename} is the name of the module).
-Internal symbols must be named in such a way that they won't conflict
-with other modules, for example, by prefixing them with "_modulename_".
-Although some platforms support having the same symbols defined more than
-once it is generally not portable and it makes it impossible to dlpreopen
-such modules. libltdl will automatically cut the prefix off to get
-the real name of the symbol. Additionally, it supports modules which
-don't use a prefix so that you can also dlopen non-libtool modules.
-
-@file{foo1.c} gives an example of a portable libtool module.
-Exported symbols are prefixed with "foo1_LTX_", internal symbols
-with "_foo1_". Aliases are defined at the beginning so that the code
-is more readable.
-
-@example
-/* aliases for the exported symbols */
-#define foo foo1_LTX_foo
-#define bar foo1_LTX_bar
-
-/* a global variable definition */
-int bar = 1;
-
-/* a private function */
-int _foo1_helper() @{
- return bar;
-@}
-
-/* an exported function */
-int foo() @{
- return _foo_helper();
-@}
-@end example
-
-@noindent
-The @file{Makefile.am} contains the necessary rules to build the
-module @file{foo1.la}:
-
-@example
-...
-lib_LTLIBRARIES = foo1.la
-
-foo1_la_SOURCES = foo1.c
-foo1_la_LDFLAGS = -module
-...
-@end example
-
-@node Distributing libltdl
-@section How to distribute libltdl with your package
-
-Even though libltdl is installed together with libtool, you may wish to
-include libltdl in the distribution of your package, for the convenience
-of users of your package that don't have libtool or libltdl installed.
-In this case, you must decide whether to manually add the @code{ltdl}
-objects to your package, or else which flavor of libltdl you want to use:
-a convenience library or an installable libtool library.
-
-The most simplistic way to add @code{ltdl} to your package is to copy
-the source files, @file{ltdl.c} and @file{ltdl.h}, to a source directory
-withing your package and to build and link them along with the rest of
-your sources. To help you do this, the m4 macros for autoconf are
-available in @file{ltdl.m4}. You must ensure that they are available in
-@file{aclocal.m4} before you run autoconf -- by appending the contents
-of @file{ltdl.m4} to @file{acinclude.m4}, if you are using automake, or
-to @file{aclocal.m4} if you are not. Having made the macros available,
-you must add a call to the @samp{AC_LIB_LTDL} macro to your package's
-@file{configure.in} to perform the configure time checks required to
-build @file{ltdl.o} correctly. This method has problems if you then try
-to link the package binaries with an installed libltdl, or a library
-which depends on libltdl: you may have problems with duplicate symbol
-definitions.
-
-One advantage of the convenience library is that it is not installed, so
-the fact that you use libltdl will not be apparent to the user, and it
-will not overwrite a pre-installed version of libltdl a user might have.
-On the other hand, if you want to upgrade libltdl for any reason
-(e.g. a bugfix) you'll have to recompile your package instead of just
-replacing an installed version of libltdl.
-However, if your programs or libraries are linked with other libraries
-that use such a pre-installed version of libltdl, you may get linker
-errors or run-time crashes. Another problem is that you cannot link the
-convenience library into more than one libtool library, then link a
-single program with these libraries, because you may get duplicate
-symbols. In general you can safely use the convenience library in programs
-which don't depend on other libraries that might use libltdl too.
-In order to enable this flavor of libltdl, you should add the
-line @samp{AC_LIBLTDL_CONVENIENCE} to your @file{configure.in},
-@emph{before} @samp{AM_PROG_LIBTOOL}.
-
-In order to select the installable version of libltdl, you should add a
-call of the macro @samp{AC_LIBLTDL_INSTALLABLE} to your
-@file{configure.in} @emph{before} @samp{AM_PROG_LIBTOOL}. This macro
-will check whether libltdl is already installed and, if not, request the
-libltdl embedded in your package to be built and installed. Note,
-however, that no version checking is performed. The user may override
-the test and determine that the libltdl embedded must be installed,
-regardless of the existence of another version, using the configure
-switch @samp{--enable-ltdl-install}.
-
-In order to embed libltdl into your package, just add @samp{--ltdl} to
-the @code{libtoolize} command line. It will copy the libltdl sources
-to a subdirectory @samp{libltdl} in your package.
-Both macros accept an optional argument to specify the location
-of the @samp{libltdl} directory. By the default both macros assume that it
-is @samp{$@{top_builddir@}/libltdl}.
-
-Whatever macro you use, it is up to you to ensure that your
-@file{configure.in} will configure libltdl, using
-@samp{AC_CONFIG_SUBDIRS}, and that your @file{Makefile}s will start
-sub-makes within libltdl's directory, using automake's @var{SUBDIRS},
-for example. Both macros define the shell variables @var{LIBLTDL}, to
-the link flag that you should use to link with libltdl, and
-@var{INCLTDL}, to the preprocessor flag that you should use to compile
-with programs that include @file{ltdl.h}. It is up to you to use
-@samp{AC_SUBST} to ensure that this variable will be available in
-@file{Makefile}s, or add them to variables that are @samp{AC_SUBST}ed by
-default, such as @var{LIBS} and @var{CPPFLAGS}.
-
-If you're using the convenience libltdl, @var{LIBLTDL} will be the
-pathname for the convenience version of libltdl and @var{INCLTDL} will be
-@samp{-I} followed by the directory that contains libltdl, both starting
-with @samp{$@{top_builddir@}/}.
-
-If you request an installed version of libltdl and one is
-found@footnote{Even if libltdl is installed,
-@samp{AC_LIBLTDL_INSTALLABLE} may fail to detect it, if libltdl depends
-on symbols provided by libraries other than the C library. In this
-case, it will needlessly build and install libltdl.}, @var{LIBLTDL} will
-be set to @samp{-lltdl} and @var{INCLTDL} will be empty (which is just a
-blind assumption that @file{ltdl.h} is somewhere in the include path if
-libltdl is in the library path). If an installable version of libltdl
-must be built, its pathname, starting with @samp{$@{top_builddir@}/},
-will be stored in @var{LIBLTDL}, and @var{INCLTDL} will be set just like
-in the case of convenience library.
-
-So, when you want to link a program with libltdl, be it a convenience,
-installed or installable library, just compile with @samp{$(INCLTDL)}
-and link it with @samp{$(LIBLTDL)}, using libtool.
-
-You should probably also add @samp{AC_LIBTOOL_DLOPEN} to your
-@file{configure.in} @emph{before} @samp{AM_PROG_LIBTOOL}, otherwise
-libtool will assume no dlopening mechanism is supported, and revert to
-dlpreopening, which is probably not what you want.
-
-Avoid using the @code{-static} or @code{-all-static} switches when
-linking programs with libltdl. This will not work on all platforms,
-because the dlopening functions may not be available for static linking.
-
-The following example shows you how to embed the convenience libltdl in
-your package. In order to use the installable variant just replace
-@samp{AC_LIBLTDL_CONVENIENCE} with @samp{AC_LIBLTDL_INSTALLABLE}. We
-assume that libltdl was embedded using @samp{libtoolize --ltdl}.
-
-configure.in:
-@example
-...
-dnl Enable building of the convenience library
-dnl and set LIBLTDL accordingly
-AC_LIBLTDL_CONVENIENCE
-dnl Substitute INCLTDL and LIBLTDL in the Makefiles
-AC_SUBST(INCLTDL)
-AC_SUBST(LIBLTDL)
-dnl Check for dlopen support
-AC_LIBTOOL_DLOPEN
-dnl Configure libtool
-AM_PROG_LIBTOOL
-dnl Configure libltdl
-AC_CONFIG_SUBDIRS(libltdl)
-...
-@end example
-
-Makefile.am:
-@example
-...
-SUBDIRS = libltdl
-
-INCLUDES = $(INCLTDL)
-
-myprog_LDFLAGS = -export-dynamic
-# The quotes around -dlopen below fool automake into accepting it
-myprog_LDADD = $(LIBLTDL) "-dlopen" self "-dlopen" libfoo.la
-myprog_DEPENDENCIES = $(LIBLTDL) libfoo.la
-...
-@end example
-
-
-@node Module loaders for libltdl
-@section How to create and register new module loaders
-
-Sometimes libltdl's many ways of gaining access to modules are not
-sufficient for the purposes of a project. You can write your own
-loader, and register it with libltdl so that @code{lt_dlopen} will be
-able to use it.
-
-Writing a loader involves writing at least three functions which can be
-called by @code{lt_dlopen}, @code{lt_dlsym} and @code{lt_dlclose}.
-Optionally, you can provide a finalisation function to perform any
-cleanup operations when @code{lt_dlexit} executes, and a symbol prefix
-string which will be prepended to any symbols passed to @code{lt_dlsym}.
-These functions must match the function pointer types below, after
-which they can be allocated to an instance of @code{lt_user_dlloader}
-and registered.
-
-Registering the loader requires that you choose a name for it, so that it
-can be recognised by @code{lt_find_dlloader} and removed with
-@code{lt_remove_dlloader}. The name you choose must be unique, and not
-already in use by libltdl's builtin loaders:
-
-@table @asis
-@item "dlopen"
-The system dynamic library loader, if one exists.
-@item "dld"
-The @sc{gnu} dld loader, if @file{libdld} wasinstalled when libltdl was
-built.
-@item "dlpreload"
-The loader for @code{lt_dlopen}ing of preloaded static modules.
-@end table
-
-The prefix "dl" is reserved for loaders supplied with future versions of
-libltdl, so you should not use that for your own loader names.
-
-@noindent
-The following types are defined in @file{ltdl.h}:
-
-@deftp {Type} lt_module_t
-@code{lt_module_t} is a dlloader dependent module.
-The dynamic module loader extensions communicate using these low
-level types.
-@end deftp
-
-@deftp {Type} lt_dlloader_t
-@code{lt_dlloader_t} is a handle for module loader types.
-@end deftp
-
-@deftypefn {Type} {struct} lt_user_dlloader @{@w{const char *@var{sym_prefix};} @w{lt_module_open_t *@var{module_open};} @w{lt_module_close_t *@var{module_close};} @w{lt_find_sym_t *@var{find_sym};} @w{lt_dlloader_exit_t *@var{dlloader_exit};} @}
-If you want to define a new way to open dynamic modules, and have the
-@code{lt_dlopen} @sc{api} use it, you need to instantiate one of these
-structures and pass it to @code{lt_add_dlloader}.
-@end deftypefn
-
-@deftypefn {Type} lt_module_t lt_module_open_t (@w{const char *@var{filename}})
-The type of the loader function for an @code{lt_dlloader_t} module
-loader. Implementation of such a function should attempt to load the
-named module, and return an @code{lt_module_t} suitable for passing in
-to the associated @code{lt_module_close_t} and @code{lt_sym_find_t}
-function pointers. If the function fails it should return NULL, and set
-the error message with @code{lt_dlseterror}.
-@end deftypefn
-
-@deftypefn {Type} int lt_module_close_t (@w{lt_module_t @var{module}})
-The type of the unloader function for a user defined module loader.
-Implementatation of such a function should attempt to release
-any resources tied up by the @var{module} module, and then unload it
-from memory. If the function fails for some reason, set the error
-message with @code{lt_dlseterror} and return non-zero.
-@end deftypefn
-
-@deftypefn {Type} lt_ptr_t lt_find_sym_t (@w{lt_module_t @var{module},} @w{const char *@var{symbol}})
-The type of the symbol lookup function for a user defined module loader.
-Implementation of such a function should return the address of the named
-@var{symbol} in the module @var{module}, or else set the error message
-with @code{lt_dlseterror} and return NULL if lookup fails.
-@end deftypefn
-
-@deftypefn {Type} int lt_dlloader_exit_t (void)
-The type of the finalisation function for a user defined module loader.
-Implementation of such a function should free any resources associated
-with the loader. If non-NULL, the function will be called by
-@code{lt_dlexit}.
-@end deftypefn
-
-For example:
-
-@example
-int
-register_myloader (void)
-@{
- lt_user_dlloader dlloader;
-
- /* User modules are responsible for their own initialisation. */
- if (myloader_init () != 0)
- return MYLOADER_INIT_ERROR;
-
- dlloader.sym_prefix = NULL;
- dlloader.module_open = myloader_open;
- dlloader.module_close = myloader_close;
- dlloader.find_sym = myloader_find_sym.
- dlloader.dlloader_exit = myloader_exit;
-
- /* Add my loader as the default module loader. */
- if (lt_add_dlloader (lt_next_dlloader (NULL), &dlloader, "myloader") != 0)
- return ERROR;
-
- return OK;
-@}
-@end example
-
-Note that if there is any initialisation required for the loader,
-it must be performed manually before the loader is registered --
-libltdl doesn't handle user loader initialisation.
-
-Finalisation @emph{is} handled by libltdl however, and it is important
-to ensure the @code{dlloader_exit} callback releases any resources claimed
-during the initialisation phase.
-
-@page
-@noindent
-libltdl provides the following functions for writing your own module
-loaders:
-
-@deftypefun int lt_add_dlloader (@w{lt_dlloader_t *@var{place},} @w{lt_user_dlloader *@var{dlloader},} @w{const char *@var{loader_name}})
-Add a new module loader to the list of all loaders, either as the
-last loader (if @var{place} is @code{NULL}), else immediately before the
-loader passed as @var{place}. @var{loader_name} will be returned by
-@code{lt_dlloader_name} if it is subsequently passed a newly
-registered loader. These @var{loader_name}s must be unique, or
-@code{lt_remove_dlloader} and @code{lt_find_dlloader} cannot
-work. Returns 0 for success.
-
-@example
-@{
- /* Make myloader be the last one. */
- if (lt_add_dlloader (NULL, myloader) != 0)
- perror (lt_dlerror ());
-@}
-@end example
-@end deftypefun
-
-@deftypefun int lt_remove_dlloader (@w{const char *@var{loader_name}})
-Remove the loader identified by the unique name, @var{loader_name}.
-Before this can succeed, all modules opened by the named loader must
-have been closed. Returns 0 for success, otherwise an error message can
-be obtained from @code{lt_dlerror}.
-
-@example
-@{
- /* Remove myloader. */
- if (lt_remove_dlloader ("myloader") != 0)
- perror (lt_dlerror ());
-@}
-@end example
-@end deftypefun
-
-@deftypefun lt_dlloader_t *lt_next_dlloader (@w{lt_dlloader_t *@var{place}})
-Iterate over the module loaders, returning the first loader if @var{place} is
-@code{NULL}, and the next one on subsequent calls. The handle is for use with
-@code{lt_add_dlloader}.
-
-@example
-@{
- /* Make myloader be the first one. */
- if (lt_add_dlloader (lt_next_dlloader (NULL), myloader) != 0)
- return ERROR;
-@}
-@end example
-@end deftypefun
-
-@deftypefun lt_dlloader_t *lt_find_dlloader (@w{const char *@var{loader_name}})
-Return the first loader with a matching @var{loader_name} identifier, or else
-@code{NULL}, if the identifier is not found.
-
-The identifiers which may be used by ltdl itself, if the host
-architecture supports them are @dfn{dlopen}@footnote{This is used for
-the host dependent module loading @sc{api} -- @code{shl_load} and
-@code{LoadLibrary} for example}, @dfn{dld} and @dfn{dlpreload}.
-
-@example
-@{
- /* Add a user loader as the next module loader to be tried if
- the standard dlopen loader were to fail when lt_dlopening. */
- if (lt_add_dlloader (lt_find_dlloader ("dlopen"), myloader) != 0)
- return ERROR;
-@}
-@end example
-@end deftypefun
-
-@deftypefun char *lt_dlloader_name (@w{lt_dlloader_t *@var{place}})
-Return the identifying name of @var{PLACE}, as obtained from
-@code{lt_next_dlloader} or @code{lt_find_dlloader}. If this function fails,
-it will return @code{NULL} and set an error for retrieval with
-@code{lt_dlerror}.
-@end deftypefun
-
-@subsection Error handling within user module loaders
-
-@deftypefun int lt_dladderror (@w{const char *@var{diagnostic}})
-This function allows you to integrate your own error messages into
-@code{lt_dlerror}. Pass in a suitable diagnostic message for return by
-@code{lt_dlerror}, and an error identifier for use with
-@code{lt_dlseterror} is returned.
-
-If the allocation of an identifier fails, this function returns -1.
-
-@example
-int myerror = lt_dladderror ("Doh!");
-if (myerror < 0)
- perror (lt_dlerror ());
-@end example
-@end deftypefun
-
-@deftypefun int lt_dlseterror (@w{int @var{errorcode}})
-When writing your own module loaders, you should use this function to
-raise errors so that they are propogated through the @code{lt_dlerror}
-interface. All of the standard errors used by libltdl are declared in
-@file{ltdl.h}, or you can add more of your own with
-@code{lt_dladderror}. This function returns 0 on success.
-
-@example
-if (lt_dlseterror (LTDL_ERROR_NO_MEMORY) != 0)
- perror (lt_dlerror ());
-@end example
-@end deftypefun
-
-@node Other languages
-@chapter Using libtool with other languages
-@cindex C, not using
-@cindex languages, non-C
-@cindex C++, using
-
-Libtool was first implemented in order to add support for writing shared
-libraries in the C language. However, over time, libtool is being
-integrated with other languages, so that programmers are free to reap
-the benefits of shared libraries in their favorite programming language.
-
-This chapter describes how libtool interacts with other languages,
-and what special considerations you need to make if you do not use C.
-
-@menu
-* Configuration tags::
-* C++ libraries::
-@end menu
-
-@node Configuration tags
-@section Configuration tags
-@cindex Configuration tags
-@cindex tags
-
-A single libtool script may support multiple configurations. By
-default, it will only support C compilation, but additional
-configuration tags can be created, using @samp{ltconfig --add-tag}, so
-that libtool can support other compilers. Such configuration tags can
-be used to select native compilers instead of cross ones, or compilers
-of other languages.
-
-For example, in order to create a tag for a C++ compiler @samp{CC}, you
-could run:
-
-@example
-$ @kbd{LTCC=gcc CC=c++ CFLAGS=-g CPPFLAGS=-Dfoo \}
-> @kbd{./ltconfig -o libtool --add-tag=CXX ltcf-cxx.sh}
-@end example
-
-@samp{ltcf-cxx.sh} is a shell script fragment that configures C++
-specific variables that get placed within the appended configuration
-tag. Another shell script called @samp{ltcf-c.sh} that contains C
-compiler configurations also exists but it should not be used by the
-user. It is used internally by the ltconfig script.
-
-Note that you should set @var{LTCC} to a valid C compiler, because
-libtool may need to compile additional C sources internally. Note also
-that, although @samp{CC} is not a C compiler, you should use variables
-such as @var{CC}, @var{CFLAGS} and @var{CPPFLAGS} to tell libtool which
-flags to use when compiling test programs.
-
-You can use existing compiler/language specific shell script fragments,
-such as @samp{ltcf-cxx.sh}, as a reference for other compilers/languages
-you would like libtool to support.
-
-A potential problem may occur if you use variables when setting
-@var{LTCC} and @var{CC}. For example, a problem will occur if you do
-the following:
-
-@example
-$ @kbd{LTCC=$CC CC=$CXX ./ltconfig -o libtool --add-tag=CXX ltcf-cxx.sh}
-@end example
-
-In this example, @var{CC} is set to the C++ compiler and LTCC is set to
-the compiler pointed to by @var{$CC}. However, @var{CC} was previously
-set to the C++ compiler @var{$CXX}, which causes LTCC to be set to the
-C++ compiler @var{$CXX}, too. This is a problem because LTCC must be a
-valid C compiler, not a C++ compiler for example.
-
-If @samp{ltconfig} is unable to determine the host type then you must
-explicitly provide a host when invoking @samp{ltconfig}. This is
-typically necessary for new very platforms and many cross-compiled
-platforms. For example, assuming that your host is @samp{i386-nto} then
-@samp{ltconfig} could be invoked as follows:
-
-@example
-$ @kbd{LTCC=$CC CC=$CXX ./ltconfig -o libtool \}
-> @kbd{--add-tag=CXX ltcf-cxx.sh i386-nto}
-@end example
-
-After a configuration tag has been added using the @samp{--add-tag}
-option, whenever you want to compile or link a library using
-@samp{c++}, you should run:
-
-@example
-$ @kbd{./libtool --mode=compile c++ -c test.cc}
-@end example
-
-Libtool will automatically detect the appropriate tagged configuration
-to use by matching the compiler used in the above command with the one
-the tagged configuration was configured with.
-
-The tagged configuration that libtool uses can be explicitly specified
-by using the @samp{--tag} option as follows:
-
-@example
-$ @kbd{./libtool --tag=CXX --mode=compile c++ -c test.cc}
-@end example
-
-Conceptually, tags are cumulative, i.e., they could only set a couple of
-configuration variables, leaving others untouched. In practice, any tag
-created with ltconfig will override all libtool configuration variables.
-Only the two pre-defined tags, @samp{disable-shared} and
-@samp{disable-static}, override a single variable, and can be used
-cumulatively, after other tags.
-
-@emph{NOTE}: C++ support may be automatically added to your package by
-adding the @code{AC_LIBTOOL_CXX} macro to your package
-@file{configure.in} file.
-
-@node C++ libraries
-@section Writing libraries for C++
-@c FIXME: in the TOC, the ++ is too large (seems to be math mode)
-@cindex trouble with C++
-@cindex pitfalls using C++
-@cindex C++, pitfalls
-
-@emph{NOTE}: The problems described in this section may no longer
-relevant due to the @samp{libtool} multi-language support. To enable
-C++ support in libtool, use the @code{AC_LIBTOOL_CXX} macro in your
-@file{configure.in} file.
-
-Creating libraries of C++ code should be a fairly straightforward
-process, because its object files differ from C ones in only three ways:
-
-@enumerate 1
-@item
-Because of name mangling, C++ libraries are only usable by the C++
-compiler that created them. This decision was made by the designers of
-C++ in order to protect users from conflicting implementations of
-features such as constructors, exception handling, and RTTI.
-
-@item
-On some systems, the C++ compiler must take special actions for the
-dynamic linker to run dynamic (i.e., run-time) initializers. This means
-that we should not call @file{ld} directly to link such libraries, and
-we should use the C++ compiler instead.
-
-@item
-C++ compilers will link some Standard C++ library in by default, but
-libtool does not know which are these libraries, so it cannot even run
-the inter-library dependence analyzer to check how to link it in.
-Therefore, running @file{ld} to link a C++ program or library is deemed
-to fail. However, running the C++ compiler directly may lead to
-problems related with inter-library dependencies.
-@end enumerate
-
-The conclusion is that libtool is not ready for general use for C++
-libraries. You should avoid any global or static variable
-initializations that would cause an ``initializer element is not
-constant'' error if you compiled them with a standard C compiler.
-
-There are other ways of working around this problem, but they are beyond
-the scope of this manual.
-
-Furthermore, you'd better find out, at configure time, what are the C++
-Standard libraries that the C++ compiler will link in by default, and
-explicitly list them in the link command line. Hopefully, in the
-future, libtool will be able to do this job by itself.
-
-
-@node Troubleshooting
-@chapter Troubleshooting
-@cindex troubleshooting
-@cindex problems, solving
-@cindex solving problems
-@cindex problems, blaming somebody else for
-
-Libtool is under constant development, changing to remain up-to-date
-with modern operating systems. If libtool doesn't work the way you
-think it should on your platform, you should read this chapter to help
-determine what the problem is, and how to resolve it.
-
-@menu
-* Libtool test suite:: Libtool's self-tests.
-* Reporting bugs:: How to report problems with libtool.
-@end menu
-
-@node Libtool test suite
-@section The libtool test suite
-@cindex test suite
-
-Libtool comes with its own set of programs that test its capabilities,
-and report obvious bugs in the libtool program. These tests, too, are
-constantly evolving, based on past problems with libtool, and known
-deficiencies in other operating systems.
-
-As described in the @file{INSTALL} file, you may run @kbd{make check}
-after you have built libtool (possibly before you install it) in order
-to make sure that it meets basic functional requirements.
-
-@menu
-* Test descriptions:: The contents of the test suite.
-* When tests fail:: What to do when a test fails.
-@end menu
-
-@node Test descriptions
-@subsection Description of test suite
-
-Here is a list of the current programs in the test suite, and what they
-test for:
-
-@table @file
-
-@item cdemo-conf.test
-@itemx cdemo-exec.test
-@itemx cdemo-make.test
-@itemx cdemo-static.test
-@itemx cdemo-shared.test
-@pindex cdemo-conf.test
-@pindex cdemo-exec.test
-@pindex cdemo-make.test
-@pindex cdemo-static.test
-@pindex cdemo-shared.test
-These programs check to see that the @file{cdemo} subdirectory of the
-libtool distribution can be configured and built correctly.
-
-The @file{cdemo} subdirectory contains a demonstration of libtool
-convenience libraries, a mechanism that allows build-time static
-libraries to be created, in a way that their components can be later
-linked into programs or other libraries, even shared ones.
-
-The tests @file{cdemo-make.test} and @file{cdemo-exec.test} are executed
-three times, under three different libtool configurations:
-@file{cdemo-conf.test} configures @file{cdemo/libtool} to build both
-static and shared libraries (the default for platforms that support
-both), @file{cdemo-static.test} builds only static libraries
-(@samp{--disable-shared}), and @file{cdemo-shared.test} builds only
-shared libraries (@samp{--disable-static}).
-
-@item demo-conf.test
-@itemx demo-exec.test
-@itemx demo-inst.test
-@itemx demo-make.test
-@itemx demo-unst.test
-@itemx demo-static.test
-@itemx demo-shared.test
-@itemx demo-nofast.test
-@itemx demo-pic.test
-@itemx demo-nopic.test
-@pindex demo-conf.test
-@pindex demo-exec.test
-@pindex demo-inst.test
-@pindex demo-make.test
-@pindex demo-unst.test
-@pindex demo-static.test
-@pindex demo-shared.test
-@pindex demo-nofast.test
-@pindex demo-pic.test
-@pindex demo-nopic.test
-These programs check to see that the @file{demo} subdirectory of the
-libtool distribution can be configured, built, installed, and
-uninstalled correctly.
-
-The @file{demo} subdirectory contains a demonstration of a trivial
-package that uses libtool. The tests @file{demo-make.test},
-@file{demo-exec.test}, @file{demo-inst.test} and
-@file{demo-unst.test} are executed four times, under four different
-libtool configurations: @file{demo-conf.test} configures
-@file{demo/libtool} to build both static and shared libraries,
-@file{demo-static.test} builds only static libraries
-(@samp{--disable-shared}), and @file{demo-shared.test} builds only
-shared libraries (@samp{--disable-static}).
-@file{demo-nofast.test} configures @file{demo/libtool} to
-disable the fast-install mode (@samp{--enable-fast-install=no}).
-@file{demo-pic.test} configures @file{demo/libtool} to
-prefer building PIC code (@samp{--with-pic}), @file{demo-nopic.test}
-to prefer non-PIC code (@samp{--without-pic}).
-
-@item deplibs.test
-@pindex deplibs.test
-Many systems cannot link static libraries into shared libraries.
-libtool uses a @code{deplibs_check_method} to prevent such cases.
-This tests checks whether libtool's @code{deplibs_check_method}
-works properly.
-
-@item hardcode.test
-@pindex hardcode.test
-On all systems with shared libraries, the location of the library can be
-encoded in executables that are linked against it @pxref{Linking
-executables}. This test checks the conditions under which your system
-linker hardcodes the library location, and guarantees that they
-correspond to libtool's own notion of how your linker behaves.
-
-@item build-relink.test
-@pindex build-relink.test
-Checks whether variable @var{shlibpath_overrides_runpath} is properly
-set. If the test fails and @var{VERBOSE} is set, it will indicate what
-the variable should have been set to.
-
-@item noinst-link.test
-@pindex noinst-link.test
-Checks whether libtool will not try to link with a previously installed
-version of a library when it should be linking with a just-built one.
-
-@item depdemo-conf.test
-@itemx depdemo-exec.test
-@itemx depdemo-inst.test
-@itemx depdemo-make.test
-@itemx depdemo-unst.test
-@itemx depdemo-static.test
-@itemx depdemo-shared.test
-@itemx depdemo-nofast.test
-@pindex depdemo-conf.test
-@pindex depdemo-exec.test
-@pindex depdemo-inst.test
-@pindex depdemo-make.test
-@pindex depdemo-unst.test
-@pindex depdemo-static.test
-@pindex depdemo-shared.test
-@pindex depdemo-nofast.test
-These programs check to see that the @file{depdemo} subdirectory of the
-libtool distribution can be configured, built, installed, and
-uninstalled correctly.
-
-The @file{depdemo} subdirectory contains a demonstration of inter-library
-dependencies with libtool. The test programs link some interdependent
-libraries.
-
-The tests @file{depdemo-make.test}, @file{depdemo-exec.test},
-@file{depdemo-inst.test} and @file{depdemo-unst.test} are executed
-four times, under four different libtool configurations:
-@file{depdemo-conf.test} configures @file{depdemo/libtool} to build both
-static and shared libraries, @file{depdemo-static.test} builds only static
-libraries (@samp{--disable-shared}), and @file{depdemo-shared.test} builds
-only shared libraries (@samp{--disable-static}).
-@file{depdemo-nofast.test} configures @file{depdemo/libtool} to
-disable the fast-install mode (@samp{--enable-fast-install=no}.
-
-@item mdemo-conf.test
-@itemx mdemo-exec.test
-@itemx mdemo-inst.test
-@itemx mdemo-make.test
-@itemx mdemo-unst.test
-@itemx mdemo-static.test
-@itemx mdemo-shared.test
-@pindex mdemo-conf.test
-@pindex mdemo-exec.test
-@pindex mdemo-inst.test
-@pindex mdemo-make.test
-@pindex mdemo-unst.test
-@pindex mdemo-static.test
-@pindex mdemo-shared.test
-These programs check to see that the @file{mdemo} subdirectory of the
-libtool distribution can be configured, built, installed, and
-uninstalled correctly.
-
-The @file{mdemo} subdirectory contains a demonstration of a package that
-uses libtool and the system independent dlopen wrapper @file{libltdl} to
-load modules. The library @file{libltdl} provides a dlopen wrapper for
-various platforms (Linux, Solaris, HP/UX etc.) including support for
-dlpreopened modules (@pxref{Dlpreopening}).
-
-The tests @file{mdemo-make.test}, @file{mdemo-exec.test},
-@file{mdemo-inst.test} and @file{mdemo-unst.test} are executed
-three times, under three different libtool configurations:
-@file{mdemo-conf.test} configures @file{mdemo/libtool} to build both
-static and shared libraries, @file{mdemo-static.test} builds only static
-libraries (@samp{--disable-shared}), and @file{mdemo-shared.test} builds
-only shared libraries (@samp{--disable-static}).
-
-@item tagdemo-conf.test
-@itemx tagdemo-exec.test
-@itemx tagdemo-make.test
-@itemx tagdemo-static.test
-@itemx tagdemo-shared.test
-@pindex tagdemo-conf.test
-@pindex tagdemo-exec.test
-@pindex tagdemo-make.test
-@pindex tagdemo-static.test
-@pindex tagdemo-shared.test
-These programs check to see that the @file{tagdemo} subdirectory of the
-libtool distribution can be configured and built correctly.
-
-The @file{tagdemo} subdirectory contains a demonstration of a package
-that uses libtool and its tagged configuration support
-(@pxref{Configuration tags}) build a C++ library. C++ shared library
-support is enabled by using the @code{AC_LIBTOOL_CXX} macro in
-@file{tagdemo/configure.in}.
-
-The tests @file{tagdemo-make.test}, and @file{tagdemo-exec.test}, are
-executed three times, under three different libtool configurations:
-@file{tagdemo-conf.test} configures @file{tagdemo/libtool} to build both
-static and shared libraries, @file{tagdemo-static.test} builds only
-static libraries (@samp{--disable-shared}), and
-@file{tagdemo-shared.test} builds only shared libraries
-(@samp{--disable-static}).
-
-@item dryrun.test
-@pindex dryrun.test
-This test checks whether libtool's @code{--dry-run} mode works properly.
-
-@item assign.test
-@pindex assign.test
-Checks whether we don't put break or continue on the same
-line as an assignment in the libtool script.
-
-@item link.test
-@pindex link.test
-This test guarantees that linking directly against a non-libtool static
-library works properly.
-
-@item link-2.test
-@pindex link-2.test
-This test makes sure that files ending in @samp{.lo} are never linked
-directly into a program file.
-
-@item nomode.test
-@pindex nomode.test
-Check whether we can actually get help for libtool.
-
-@item quote.test
-@pindex quote.test
-This program checks libtool's metacharacter quoting.
-
-@item sh.test
-@pindex sh.test
-Checks whether a `test' command was forgotten in libtool.
-
-@item suffix.test
-@pindex suffix.test
-When other programming languages are used with libtool (@pxref{Other
-languages}), the source files may end in suffixes other than @samp{.c}.
-This test validates that libtool can handle suffixes for all the file
-types that it supports, and that it fails when the suffix is invalid.
-
-@end table
-
-@node When tests fail
-@subsection When tests fail
-@cindex failed tests
-@cindex tests, failed
-
-Each of the above tests are designed to produce no output when they are
-run via @kbd{make check}. The exit status of each program tells the
-@file{Makefile} whether or not the test succeeded.
-
-If a test fails, it means that there is either a programming error in
-libtool, or in the test program itself.
-
-To investigate a particular test, you may run it directly, as you would
-a normal program. When the test is invoked in this way, it produces
-output which may be useful in determining what the problem is.
-
-Another way to have the test programs produce output is to set the
-@var{VERBOSE} environment variable to @samp{yes} before running them.
-For example, @kbd{env VERBOSE=yes make check} runs all the tests, and
-has each of them display debugging information.
-
-@node Reporting bugs
-@section Reporting bugs
-@cindex bug reports
-@cindex reporting bugs
-@cindex problem reports
-
-If you think you have discovered a bug in libtool, you should think
-twice: the libtool maintainer is notorious for passing the buck (or
-maybe that should be ``passing the bug''). Libtool was invented to fix
-known deficiencies in shared library implementations, so, in a way, most
-of the bugs in libtool are actually bugs in other operating systems.
-However, the libtool maintainer would definitely be happy to add support
-for somebody else's buggy operating system. [I wish there was a good
-way to do winking smiley-faces in Texinfo.]
-
-Genuine bugs in libtool include problems with shell script portability,
-documentation errors, and failures in the test suite (@pxref{Libtool
-test suite}).
-
-First, check the documentation and help screens to make sure that the
-behaviour you think is a problem is not already mentioned as a feature.
-
-Then, you should read the Emacs guide to reporting bugs (@pxref{Bugs, ,
-Reporting Bugs, emacs, The Emacs Manual}). Some of the details
-listed there are specific to Emacs, but the principle behind them is a
-general one.
-
-Finally, send a bug report to @value{BUGADDR} with any appropriate
-@emph{facts}, such as test suite output (@pxref{When tests fail}), all
-the details needed to reproduce the bug, and a brief description of why
-you think the behaviour is a bug. Be sure to include the word
-``libtool'' in the subject line, as well as the version number you are
-using (which can be found by typing @kbd{ltconfig --version}).
-
-@node Maintaining
-@chapter Maintenance notes for libtool
-
-This chapter contains information that the libtool maintainer finds
-important. It will be of no use to you unless you are considering
-porting libtool to new systems, or writing your own libtool.
-
-@menu
-* 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.
-@end menu
-
-@node New ports
-@section Porting libtool to new systems
-
-Before you embark on porting libtool to an unsupported system, it is
-worthwhile to send e-mail to @value{MAILLIST}, to make sure that you are
-not duplicating existing work.
-
-If you find that any porting documentation is missing, please complain!
-Complaints with patches and improvements to the documentation, or to
-libtool itself, are more than welcome.
-
-@menu
-* Information sources:: Where to find relevant documentation
-* Porting inter-library dependencies:: Implementation details explained
-@end menu
-
-@node Information sources
-@subsection Information sources
-
-Once it is clear that a new port is necessary, you'll generally need the
-following information:
-
-@table @asis
-@item canonical system name
-You need the output of @code{config.guess} for this system, so that you
-can make changes to the libtool configuration process without affecting
-other systems.
-
-@item man pages for @code{ld} and @code{cc}
-These generally describe what flags are used to generate PIC, to create
-shared libraries, and to link against only static libraries. You may
-need to follow some cross references to find the information that is
-required.
-
-@item man pages for @code{ld.so}, @code{rtld}, or equivalent
-These are a valuable resource for understanding how shared libraries are
-loaded on the system.
-
-@item man page for @code{ldconfig}, or equivalent
-This page usually describes how to install shared libraries.
-
-@item output from @kbd{ls -l /lib /usr/lib}
-This shows the naming convention for shared libraries on the system,
-including which names should be symbolic links.
-
-@item any additional documentation
-Some systems have special documentation on how to build and install
-shared libraries.
-@end table
-
-If you know how to program the Bourne shell, then you can complete the
-port yourself; otherwise, you'll have to find somebody with the relevant
-skills who will do the work. People on the libtool mailing list are
-usually willing to volunteer to help you with new ports, so you can send
-the information to them.
-
-To do the port yourself, you'll definitely need to modify the
-@code{ltconfig} script in order to make platform-specific changes to the
-configuration process. You should search the script for the
-@code{PORTME} keyword, which will give you some hints on what you'll
-need to change. In general, all that is involved is modifying the
-appropriate configuration variables (@pxref{libtool script contents}).
-
-Your best bet is to find an already-supported system that is similar to
-yours, and make your changes based on that. In some cases, however,
-your system will differ significantly from every other supported system,
-and it may be necessary to add new configuration variables, and modify
-the @code{ltmain.sh} script accordingly. Be sure to write to the
-mailing list before you make changes to @code{ltmain.sh}, since they may
-have advice on the most effective way of accomplishing what you want.
-
-@node Porting inter-library dependencies
-@subsection Porting inter-library dependencies support
-@cindex inter-library dependency
-@vindex deplibs_check_method
-
-Since version 1.2c, libtool has re-introduced the ability to do
-inter-library dependency on some platforms, thanks to a patch by Toshio
-Kuratomi @email{badger@@prtr-13.ucsc.edu}. Here's a shortened version
-of the message that contained his patch:
-
-The basic architecture is this: in @file{ltconfig.in}, the person who
-writes libtool makes sure @samp{$deplibs} is included in
-@samp{$archive_cmds} somewhere and also sets the variable
-@samp{$deplibs_check_method}, and maybe @samp{$file_magic_cmd} when
-@samp{deplibs_check_method} is file_magic.
-
-@samp{deplibs_check_method} can be one of five things:
-@table @samp
-@item file_magic [@var{regex}]
-@vindex file_magic
-@vindex file_magic_cmd
-@vindex file_magic_test_file
-looks in the library link path for libraries that have the right
-libname. Then it runs @samp{$file_magic_cmd} on the library and checks
-for a match against @samp{regex} using @code{egrep}. When
-@var{file_magic_test_file} is set in @file{ltconfig}, it is used as an
-argument to @samp{$file_magic_cmd} in order to verify whether the
-regular expression matches its output, and warn the user otherwise.
-
-@item test_compile
-@vindex test_compile
-just checks whether it is possible to link a program out of a list of
-libraries, and checks which of those are listed in the output of
-@code{ldd}. It is currently unused, and will probably be dropped in the
-future.
-
-@item pass_all
-@vindex pass_all
-will pass everything without any checking. This may work on platforms
-in which code is position-independent by default and inter-library
-dependencies are properly supported by the dynamic linker, for example,
-on DEC OSF/1 3 and 4.
-
-@item none
-@vindex none
-It causes deplibs to be reassigned deplibs="". That way
-@samp{archive_cmds} can contain deplibs on all platforms, but not have
-deplibs used unless needed.
-
-@item unknown
-@vindex unknown
-is the default for all systems unless overridden in @file{ltconfig.in}.
-It is the same as @samp{none}, but it documents that we really don't
-know what the correct value should be, and we welcome patches that
-improve it.
-@end table
-
-Then in @file{ltmain.in} we have the real workhorse: a little
-initialization and postprocessing (to setup/release variables for use
-with eval echo libname_spec etc.) and a case statement that decides
-which method is being used. This is the real code... I wish I could
-condense it a little more, but I don't think I can without function
-calls. I've mostly optimized it (moved things out of loops, etc) but
-there is probably some fat left. I thought I should stop while I was
-ahead, work on whatever bugs you discover, etc before thinking about
-more than obvious optimizations.
-
-@node Tested platforms
-@section Tested platforms
-
-This table describes when libtool was last known to be tested on
-platforms where it claims to support shared libraries:
-
-@example
-@include PLATFORMS
-@end example
-
-Note: The vendor-distributed HP-UX @code{sed}(1) programs are horribly
-broken, and cannot handle libtool's requirements, so users may report
-unusual problems. There is no workaround except to install a working
-@code{sed} (such as GNU @code{sed}) on these systems.
-
-Note: The vendor-distributed NCR MP-RAS @code{cc} programs emits
-copyright on standard error that confuse tests on size of
-@file{conftest.err}. The workaround is to specify @code{CC}
-when run @code{configure} with @kbd{CC='cc -Hnocopyr'}.
-
-@node Platform quirks
-@section Platform quirks
-
-This section is dedicated to the sanity of the libtool maintainers. It
-describes the programs that libtool uses, how they vary from system to
-system, and how to test for them.
-
-Because libtool is a shell script, it can be difficult to understand
-just by reading it from top to bottom. This section helps show why
-libtool does things a certain way. Combined with the scripts
-themselves, you should have a better sense of how to improve libtool, or
-write your own.
-
-@menu
-* References:: Finding more information.
-* Compilers:: Creating object files from source files.
-* Reloadable objects:: Binding object files together.
-* Archivers:: Programs that create static archives.
-@end menu
-
-@node References
-@subsection References
-
-The following is a list of valuable documentation references:
-
-@itemize @bullet
-@item
-SGI's IRIX Manual Pages, which can be found at
-@url{http://techpubs.sgi.com/cgi-bin/infosrch.cgi?cmd=browse&db=man}.
-
-@item
-Sun's free service area
-(@url{http://www.sun.com/service/online/free.html}) and documentation
-server (@url{http://docs.sun.com/}).
-@end itemize
-
-@node Compilers
-@subsection Compilers
-
-The only compiler characteristics that affect libtool are the flags
-needed (if any) to generate PIC objects. In general, if a C compiler
-supports certain PIC flags, then any derivative compilers support the
-same flags. Until there are some noteworthy exceptions to this rule,
-this section will document only C compilers.
-
-The following C compilers have standard command line options, regardless
-of the platform:
-
-@table @code
-@item gcc
-
-This is the GNU C compiler, which is also the system compiler for many
-free operating systems (FreeBSD, GNU/Hurd, GNU/Linux, Lites, NetBSD, and
-OpenBSD, to name a few).
-
-The @samp{-fpic} or @samp{-fPIC} flags can be used to generate
-position-independent code. @samp{-fPIC} is guaranteed to generate
-working code, but the code is slower on m68k, m88k, and Sparc chips.
-However, using @samp{-fpic} on those chips imposes arbitrary size limits
-on the shared libraries.
-@end table
-
-The rest of this subsection lists compilers by the operating system that
-they are bundled with:
-
-@c FIXME these should all be better-documented
-
-@table @code
-@item aix3*
-@itemx aix4*
-AIX compilers have no PIC flags, since AIX has been ported only to
-PowerPC and RS/6000 chips. @footnote{All code compiled for the PowerPC
-and RS/6000 chips (@code{powerpc-*-*}, @code{powerpcle-*-*}, and
-@code{rs6000-*-*}) is position-independent, regardless of the operating
-system or compiler suite. So, ``regular objects'' can be used to build
-shared libraries on these systems and no special PIC compiler flags are
-required.}
-
-@item hpux10*
-Use @samp{+Z} to generate PIC.
-
-@item osf3*
-Digital/UNIX 3.x does not have PIC flags, at least not on the PowerPC
-platform.
-
-@item solaris2*
-Use @samp{-KPIC} to generate PIC.
-
-@item sunos4*
-Use @samp{-PIC} to generate PIC.
-@end table
-
-@node Reloadable objects
-@subsection Reloadable objects
-
-On all known systems, a reloadable object can be created by running
-@kbd{ld -r -o @var{output}.o @var{input1}.o @var{input2}.o}. This
-reloadable object may be treated as exactly equivalent to other
-objects.
-
-@node Archivers
-@subsection Archivers
-
-On all known systems, building a static library can be accomplished by
-running @kbd{ar cru lib@var{name}.a @var{obj1}.o @var{obj2}.o @dots{}},
-where the @samp{.a} file is the output library, and each @samp{.o} file is an
-object file.
-
-On all known systems, if there is a program named @code{ranlib}, then it
-must be used to ``bless'' the created library before linking against it,
-with the @kbd{ranlib lib@var{name}.a} command. Some systems, like Irix,
-use the @code{ar ts} command, instead.
-
-@node libtool script contents
-@section @code{libtool} script contents
-@cindex implementation of libtool
-@cindex libtool implementation
-
-The @code{libtool} script is generated by @code{ltconfig}
-(@pxref{Configuring}). From libtool version 0.7 to 1.0, this script
-simply set shell variables, then sourced the libtool backend,
-@code{ltmain.sh}. @code{ltconfig} from libtool version 1.1 and later
-inlines the contents of @code{ltmain.sh} into the generated
-@code{libtool}, which improves performance on many systems.
-
-The convention used for naming variables which hold shell commands for
-delayed evaluation, is to use the suffix @code{_cmd} where a single
-line of valid shell script is needed, and the suffix @code{_cmds} where
-multiple lines of shell script @strong{may} be delayed for later
-evaluation. By convention, @code{_cmds} variables delimit the
-evaluation units with the @code{~} character where necessary.
-
-Here is a listing of each of the configuration variables, and how they
-are used within @code{ltmain.sh}:
-
-@defvar AR
-The name of the system library archiver.
-@end defvar
-
-@defvar CC
-The name of the C compiler used to configure libtool.
-@end defvar
-
-@defvar LD
-The name of the linker that libtool should use internally for reloadable
-linking and possibly shared libraries.
-@end defvar
-
-@defvar LTCONFIG_VERSION
-This is set to the version number of the @code{ltconfig} script, to
-prevent mismatches between the configuration information in
-@code{libtool}, and how that information is used in @code{ltmain.sh}.
-@end defvar
-
-@defvar NM
-The name of a BSD-compatible @code{nm} program, which produces listings
-of global symbols in one the following formats:
-
-@example
-@var{address} C @var{global-variable-name}
-@var{address} D @var{global-variable-name}
-@var{address} T @var{global-function-name}
-@end example
-@end defvar
-
-@defvar RANLIB
-Set to the name of the ranlib program, if any.
-@end defvar
-
-@defvar allow_undefined_flag
-The flag that is used by @samp{archive_cmds} in order to declare that
-there will be unresolved symbols in the resulting shared library.
-Empty, if no such flag is required. Set to @samp{unsupported} if there
-is no way to generate a shared library with references to symbols that
-aren't defined in that library.
-@end defvar
-
-@defvar always_export_symbols
-Whether libtool should automatically generate a list of exported symbols
-using @var{export_symbols_cmds} before linking an archive.
-Set to @samp{yes} or @samp{no}. Default is @samp{no}.
-@end defvar
-
-@defvar archive_cmds
-@defvarx archive_expsym_cmds
-@defvarx old_archive_cmds
-Commands used to create shared libraries, shared libraries with
-@samp{-export-symbols} and static libraries, respectively.
-@end defvar
-
-@defvar old_archive_from_new_cmds
-If the shared library depends on a static library,
-@samp{old_archive_from_new_cmds} contains the commands used to create that
-static library. If this variable is not empty, @samp{old_archive_cmds} is
-not used.
-@end defvar
-
-@defvar old_archive_from_expsyms_cmds
-If a static library must be created from the export symbol list in order to
-correctly link with a shared library, @samp{old_archive_from_expsyms_cmds}
-contains the commands needed to create that static library. When these
-commands are executed, the variable @var{soname} contains the name of the
-shared library in question, and the @var{$objdir/$newlib} contains the
-path of the static library these commands should build. After executing
-these commands, libtool will proceed to link against @var{$objdir/$newlib}
-instead of @var{soname}.
-@end defvar
-
-@defvar build_libtool_libs
-Whether libtool should build shared libraries on this system. Set to
-@samp{yes} or @samp{no}.
-@end defvar
-
-@defvar build_old_libs
-Whether libtool should build static libraries on this system. Set to
-@samp{yes} or @samp{no}.
-@end defvar
-
-@defvar compiler_c_o
-Whether the compiler supports the @code{-c} and @code{-o} options
-simultaneously. Set to @samp{yes} or @samp{no}.
-@end defvar
-
-@defvar compiler_o_lo
-Whether the compiler supports compiling directly to a ".lo" file,
-i.e whether object files do not have to have the suffix ".o".
-Set to @samp{yes} or @samp{no}.
-@end defvar
-
-@defvar dlopen_support
-Whether @code{dlopen} is supported on the platform.
-Set to @samp{yes} or @samp{no}.
-@end defvar
-
-@defvar dlopen_self
-Whether it is possible to @code{dlopen} the executable itself.
-Set to @samp{yes} or @samp{no}.
-@end defvar
-
-@defvar dlopen_self_static
-Whether it is possible to @code{dlopen} the executable itself, when it
-is linked statically (@samp{-all-static}). Set to @samp{yes} or
-@samp{no}.
-@end defvar
-
-@defvar echo
-An @code{echo} program which does not interpret backslashes as an
-escape character.
-@end defvar
-
-@defvar exclude_expsyms
-List of symbols that should not be listed in the preloaded symbols.
-@end defvar
-
-@defvar export_dynamic_flag_spec
-Compiler link flag that allows a dlopened shared library to reference
-symbols that are defined in the program.
-@end defvar
-
-@defvar export_symbols_cmds
-Commands to extract exported symbols from @var{libobjs} to the
-file @var{export_symbols}.
-@end defvar
-
-@defvar extract_expsyms_cmds
-Commands to extract the exported symbols list from a shared library.
-These commands are executed if there is no file @var{$objdir/$soname-def},
-and should write the names of the exported symbols to that file, for
-the use of @samp{old_archive_from_expsyms_cmds}.
-@end defvar
-
-@defvar fast_install
-Determines whether libtool will privilege the installer or the
-developer. The assumption is that installers will seldom run programs
-in the build tree, and the developer will seldom install. This is only
-meaningful on platforms in which @var{shlibpath_overrides_runpath} is
-not @samp{yes}, so @var{fast_install} will be set to @samp{needless} in
-this case. If @var{fast_install} set to @samp{yes}, libtool will create
-programs that search for installed libraries, and, if a program is run
-in the build tree, a new copy will be linked on-demand to use the
-yet-to-be-installed libraries. If set to @samp{no}, libtool will create
-programs that use the yet-to-be-installed libraries, and will link
-a new copy of the program at install time. The default value is
-@samp{yes} or @samp{needless}, depending on platform and configuration
-flags, and it can be turned from @samp{yes} to @samp{no} with the
-configure flag @samp{--disable-fast-install}.
-@end defvar
-
-@defvar finish_cmds
-Commands to tell the dynamic linker how to find shared libraries in a
-specific directory.
-@end defvar
-
-@defvar finish_eval
-Same as @var{finish_cmds}, except the commands are not displayed.
-@end defvar
-
-@defvar fix_srcfile_path
-Expression to fix the shell variable $srcfile for the compiler.
-@end defvar
-
-@defvar global_symbol_pipe
-A pipeline that takes the output of @var{NM}, and produces a listing of
-raw symbols followed by their C names. For example:
-
-@example
-$ @kbd{eval "$NM progname | $global_symbol_pipe"}
-D @var{symbol1} @var{C-symbol1}
-T @var{symbol2} @var{C-symbol2}
-C @var{symbol3} @var{C-symbol3}
-@dots{}
-$
-@end example
-
-The first column contains the symbol type (used to tell data from code
-on some platforms), but its meaning is system dependent.
-@end defvar
-
-@defvar global_symbol_to_cdecl
-A pipeline that translates the output of @var{global_symbol_pipe} into
-proper C declarations. On platforms whose linkers differentiate code
-from data, such as HP/UX, data symbols will be declared as such, and
-code symbols will be declared as functions. On platforms that don't
-care, everything is assumed to be data.
-@end defvar
-
-@defvar hardcode_action
-Either @samp{immediate} or @samp{relink}, depending on whether shared
-library paths can be hardcoded into executables before they are installed,
-or if they need to be relinked.
-@end defvar
-
-@defvar hardcode_direct
-Set to @samp{yes} or @samp{no}, depending on whether the linker
-hardcodes directories if a library is directly specified on the command
-line (such as @samp{@var{dir}/lib@var{name}.a}) when
-@var{hardcode_libdir_flag_spec} is specified.
-@end defvar
-
-@defvar hardcode_into_libs
-Whether the platform supports hardcoding of run-paths into libraries.
-If enabled, linking of programs will be much simpler but libraries will
-need to be relinked during installation. Set to @samp{yes} or @samp{no}.
-@end defvar
-
-@defvar hardcode_libdir_flag_spec
-Flag to hardcode a @var{libdir} variable into a binary, so that the
-dynamic linker searches @var{libdir} for shared libraries at runtime.
-If it is empty, libtool will try to use some other hardcoding mechanism.
-@end defvar
-
-@defvar hardcode_libdir_separator
-If the compiler only accepts a single @var{hardcode_libdir_flag}, then
-this variable contains the string that should separate multiple
-arguments to that flag.
-@end defvar
-
-@defvar hardcode_minus_L
-Set to @samp{yes} or @samp{no}, depending on whether the linker
-hardcodes directories specified by @samp{-L} flags into the resulting
-executable when @var{hardcode_libdir_flag_spec} is specified.
-@end defvar
-
-@defvar hardcode_shlibpath_var
-Set to @samp{yes} or @samp{no}, depending on whether the linker
-hardcodes directories by writing the contents of @samp{$shlibpath_var}
-into the resulting executable when @var{hardcode_libdir_flag_spec} is
-specified. Set to @samp{unsupported} if directories specified by
-@samp{$shlibpath_var} are searched at run time, but not at link time.
-@end defvar
-
-@defvar host
-@defvarx host_alias
-For information purposes, set to the specified and canonical names of
-the system that libtool was configured for.
-@end defvar
-
-@defvar include_expsyms
-List of symbols that must always be exported when using @var{export_symbols}.
-@end defvar
-
-@defvar libext
-The standard old archive suffix (normally "a").
-@end defvar
-
-@defvar libname_spec
-The format of a library name prefix. On all Unix systems, static
-libraries are called @samp{lib@var{name}.a}, but on some systems (such
-as OS/2 or MS-DOS), the library is just called @samp{@var{name}.a}.
-@end defvar
-
-@defvar library_names_spec
-A list of shared library names. The first is the name of the file,
-the rest are symbolic links to the file. The name in the list is
-the file name that the linker finds when given @samp{-l@var{name}}.
-@end defvar
-
-@defvar link_all_deplibs
-Whether libtool must link a program against all its dependency libraries.
-Set to @samp{yes} or @samp{no}. Default is @samp{unknown}, which is
-a synonym for @samp{yes}.
-@end defvar
-
-@defvar link_static_flag
-Linker flag (passed through the C compiler) used to prevent dynamic
-linking.
-@end defvar
-
-@defvar need_lib_prefix
-Whether libtool should automatically prefix module names with 'lib'.
-Set to @samp{yes} or @samp{no}. By default, it is @samp{unknown}, which
-means the same as @samp{yes}, but documents that we are not really sure
-about it.
-@samp{yes} means that it is possible both to @code{dlopen} and to
-link against a library without 'lib' prefix,
-i.e. it requires @var{hardcode_direct} to be @samp{yes}.
-@end defvar
-
-@defvar need_version
-Whether versioning is required for libraries, i.e. whether the
-dynamic linker requires a version suffix for all libraries.
-Set to @samp{yes} or @samp{no}. By default, it is @samp{unknown}, which
-means the same as @samp{yes}, but documents that we are not really sure
-about it.
-@end defvar
-
-@defvar need_locks
-Whether files must be locked to prevent conflicts when compiling
-simultaneously. Set to @samp{yes} or @samp{no}.
-@end defvar
-
-@defvar no_builtin_flag
-Compiler flag to disable builtin functions that conflict with declaring
-external global symbols as @code{char}.
-@end defvar
-
-@defvar no_undefined_flag
-The flag that is used by @samp{archive_cmds} in order to declare that
-there will be no unresolved symbols in the resulting shared library.
-Empty, if no such flag is required.
-@end defvar
-
-@defvar objdir
-The name of the directory that contains temporary libtool files.
-@end defvar
-
-@defvar objext
-The standard object file suffix (normally "o").
-@end defvar
-
-@defvar pic_flag
-Any additional compiler flags for building library object files.
-@end defvar
-
-@defvar postinstall_cmds
-@defvarx old_postinstall_cmds
-Commands run after installing a shared or static library, respectively.
-@end defvar
-
-@defvar postuninstall_cmds
-@defvarx old_postuninstall_cmds
-Commands run after uninstalling a shared or static library, respectively.
-@end defvar
-
-@defvar reload_cmds
-@defvarx reload_flag
-Commands to create a reloadable object.
-@end defvar
-
-@defvar runpath_var
-The environment variable that tells the linker which directories to
-hardcode in the resulting executable.
-@end defvar
-
-@defvar shlibpath_overrides_runpath
-Indicates whether it is possible to override the hard-coded library
-search path of a program with an environment variable. If this is set
-to no, libtool may have to create two copies of a program in the build
-tree, one to be installed and one to be run in the build tree only.
-When each of these copies is created depends on the value of
-@code{fast_install}. The default value is @samp{unknown}, which is
-equivalent to @samp{no}.
-@end defvar
-
-@defvar shlibpath_var
-The environment variable that tells the dynamic linker where to find
-shared libraries.
-@end defvar
-
-@defvar soname_spec
-The name coded into shared libraries, if different from the real name of
-the file.
-@end defvar
-
-@defvar striplib
-@defvarx old_striplib
-Command to strip a shared (@code{striplib}) or static (@code{old_striplib})
-library, respectively. If these variables are empty, the strip flag
-in the install mode will be ignored for libraries (@pxref{Install mode}).
-@end defvar
-
-@defvar sys_lib_dlsearch_path_spec
-Expression to get the run-time system library search path. Directories
-that appear in this list are never hard-coded into executables.
-@end defvar
-
-@defvar sys_lib_search_path_spec
-Expression to get the compile-time system library search path. This
-variable is used by libtool when it has to test whether a certain
-library is shared or static. The directories listed in
-@var{shlibpath_var} are automatically appended to this list, every time
-libtool runs (i.e., not at configuration time), because some linkers use
-this variable to extend the library search path. Linker switches such
-as @code{-L} also augment the search path.
-@end defvar
-
-@defvar thread_safe_flag_spec
-Linker flag (passed through the C compiler) used to generate thread-safe
-libraries.
-@end defvar
-
-@defvar version_type
-The library version numbering type. One of @samp{libtool},
-@samp{linux}, @samp{osf}, @samp{sunos}, or @samp{none}.
-@end defvar
-
-@defvar whole_archive_flag_spec
-Compiler flag to generate shared objects from convenience archives.
-@end defvar
-
-@defvar wl
-The C compiler flag that allows libtool to pass a flag directly to the
-linker. Used as: @code{$@{wl@}@var{some-flag}}.
-@end defvar
-
-Variables ending in @samp{_cmds} or @samp{_eval} contain a
-semicolon-separated list of commands that are @code{eval}ed one after
-another. If any of the commands return a nonzero exit status, libtool
-generally exits with an error message.
-
-Variables ending in @samp{_spec} are @code{eval}ed before being used by
-libtool.
-
-@node Cheap tricks
-@section Cheap tricks
-
-Here are a few tricks that you can use in order to make maintainership
-easier:
-
-@itemize @bullet
-@item
-When people report bugs, ask them to use the @samp{--config},
-@samp{--debug}, or @samp{--features} flags, if you think they will help
-you. These flags are there to help you get information directly, rather
-than having to trust second-hand observation.
-
-@item
-Rather than reconfiguring libtool every time I make a change to
-@code{ltconfig.in} or @code{ltmain.in}, I keep a permanent
-@code{libtool} script in my @var{PATH}, which sources @code{ltmain.in}
-directly.
-
-The following steps describe how to create such a script, where
-@code{/home/src/libtool} is the directory containing the libtool source
-tree, @code{/home/src/libtool/libtool} is a libtool script that has been
-configured for your platform, and @code{~/bin} is a directory in your
-@var{PATH}:
-
-@example
-trick$ @kbd{cd ~/bin}
-trick$ @kbd{sed '/^# ltmain\.sh/q' /home/src/libtool/libtool > libtool}
-trick$ @kbd{cat >> libtool
-LTCONFIG_VERSION="@@VERSION@@"
-. /home/src/libtool/ltmain.in
-^D}
-trick$ @kbd{chmod +x libtool}
-trick$ @kbd{libtool --version}
-ltmain.sh (GNU @@PACKAGE@@) @@VERSION@@
-trick$
-@end example
-@end itemize
-
-The output of the final @samp{libtool --version} command shows that the
-@code{ltmain.in} script is being used directly. Now, modify
-@code{~/bin/libtool} or @code{/home/src/libtool/ltmain.in} directly in
-order to test new changes without having to rerun @code{ltconfig}.
-
-@page
-@node Index
-@unnumbered Index
-
-@printindex cp
-
-@c summarycontents
-@contents
-@bye
+As a rule of thumb, link a libtool convenience library into at most one\r
+libtool library, and never into a program, and link libtool static\r
+convenience libraries only into programs, and only if you need to carry\r
+library dependency information to the user of the static convenience\r
+library.\r
+\r
+@cindex standalone binaries\r
+Another common situation where static linking is desirable is in\r
+creating a standalone binary. Use libtool to do the linking and add the\r
+@samp{-all-static} flag.\r
+\r
+@node Invoking libtool\r
+@chapter Invoking @code{libtool}\r
+@pindex libtool\r
+@cindex libtool command options\r
+@cindex options, libtool command\r
+@cindex command options, libtool\r
+\r
+The @code{libtool} program has the following synopsis:\r
+\r
+@example\r
+libtool [@var{option}]@dots{} [@var{mode-arg}]@dots{}\r
+@end example\r
+\r
+@noindent\r
+and accepts the following options:\r
+\r
+@table @samp\r
+@item --config\r
+Display libtool configuration variables and exit.\r
+\r
+@item --debug\r
+Dump a trace of shell script execution to standard output. This\r
+produces a lot of output, so you may wish to pipe it to @code{less} (or\r
+@code{more}) or redirect to a file.\r
+\r
+@item -n\r
+@itemx --dry-run\r
+Don't create, modify, or delete any files, just show what commands would\r
+be executed by libtool.\r
+\r
+@item --features\r
+Display basic configuration options. This provides a way for packages\r
+to determine whether shared or static libraries will be built.\r
+\r
+@item --finish\r
+Same as @samp{--mode=finish}.\r
+\r
+@item --help\r
+Display a help message and exit. If @samp{--mode=@var{mode}} is\r
+specified, then detailed help for @var{mode} is\r
+displayed.\r
+ \r
+@item --tag=@var{tag}\r
+Select configuration tag @var{tag}. Additional configuration tags can\r
+be created with @code{ltconfig --add-tag}. Multiple @samp{--tag} flags\r
+can be specified. In general, one tag will completely replace the\r
+configuration of the other, but the two pre-defined configuration tags,\r
+@samp{disable-shared} and @samp{disable-static}, if used @emph{after}\r
+any other, cause libtool not to create shared or static libraries,\r
+respectively, regardless of the corresponding flags used for\r
+@code{ltconfig}.\r
+\r
+@item --mode=@var{mode}\r
+Use @var{mode} as the operation mode. By default, the operation mode is\r
+inferred from the @var{mode-args}.\r
+\r
+If @var{mode} is specified, it must be one of the following:\r
+\r
+@table @samp\r
+@item compile\r
+Compile a source file into a libtool object.\r
+\r
+@item execute\r
+Automatically set the library path so that another program can use\r
+uninstalled libtool-generated programs or libraries.\r
+\r
+@item finish\r
+Complete the installation of libtool libraries on the system.\r
+\r
+@item install\r
+Install libraries or executables.\r
+\r
+@item link\r
+Create a library or an executable.\r
+\r
+@item uninstall\r
+Delete installed libraries or executables.\r
+\r
+@item clean\r
+Delete uninstalled libraries or executables.\r
+@end table\r
+\r
+@item --version\r
+Print libtool version information and exit.\r
+@end table\r
+\r
+The @var{mode-args} are a variable number of arguments, depending on the\r
+selected operation mode. In general, each @var{mode-arg} is interpreted\r
+by programs libtool invokes, rather than libtool itself.\r
+\r
+@menu\r
+* Compile mode:: Creating library object files.\r
+* Link mode:: Generating executables and libraries.\r
+* Execute mode:: Debugging libtool-generated programs.\r
+* Install mode:: Making libraries and executables public.\r
+* Finish mode:: Completing a library installation.\r
+* Uninstall mode:: Removing installed executables and libraries.\r
+* Clean mode:: Removing uninstalled executables and libraries.\r
+@end menu\r
+\r
+@node Compile mode\r
+@section Compile mode\r
+@cindex mode, compile\r
+@cindex compile mode\r
+\r
+For @dfn{compile} mode, @var{mode-args} is a compiler command to be used\r
+in creating a `standard' object file. These arguments should begin with\r
+the name of the C compiler, and contain the @samp{-c} compiler flag so\r
+that only an object file is created.\r
+\r
+Libtool determines the name of the output file by removing the directory\r
+component from the source file name, then substituting the source code\r
+suffix (e.g. @samp{.c} for C source code) with the library object suffix,\r
+@samp{.lo}.\r
+\r
+If shared libraries are being built, any necessary PIC generation flags\r
+are substituted into the compilation command.\r
+You can pass compiler and linker specific flags using @samp{-Wc,@var{flag}}\r
+and @samp{-Xcompiler @var{flag}} or @samp{-Wl,@var{flag}} and\r
+@samp{-Xlinker @var{flag}}, respectively.\r
+\r
+If the @samp{-static} option is given, then a @samp{.o} file is built,\r
+even if libtool was configured with @samp{--disable-static}.\r
+\r
+Note that the @samp{-o} option is now fully supported. It is emulated\r
+on the platforms that don't support it (by locking and moving the\r
+objects), so it is really easy to use libtool, just with minor\r
+modifications to your Makefiles. Typing for example\r
+@example\r
+libtool gcc -c foo/x.c -o foo/x.lo\r
+@end example\r
+will do what you expect.\r
+\r
+Note, however, that, if the compiler does not support @samp{-c} and\r
+@samp{-o}, it is impossible to compile @file{foo/x.c} without\r
+overwriting an existing @file{./x.o}. Therefore, if you do have a\r
+source file @file{./x.c}, make sure you introduce dependencies in your\r
+@file{Makefile} to make sure @file{./x.o} (or @file{./x.lo}) is\r
+re-created after any sub-directory's @file{x.lo}:\r
+@example\r
+x.o x.lo: foo/x.lo bar/x.lo\r
+@end example\r
+This will also ensure that make won't try to use a temporarily corrupted\r
+@file{x.o} to create a program or library. It may cause needless\r
+recompilation on platforms that support @samp{-c} and @samp{-o}\r
+together, but it's the only way to make it safe for those that don't.\r
+\r
+@node Link mode\r
+@section Link mode\r
+@cindex link mode\r
+@cindex mode, link\r
+\r
+@dfn{Link} mode links together object files (including library\r
+objects) to form another library or to create an executable program.\r
+\r
+@var{mode-args} consist of a command using the C compiler to create an\r
+output file (with the @samp{-o} flag) from several object files.\r
+\r
+The following components of @var{mode-args} are treated specially:\r
+\r
+@table @samp\r
+@cindex undefined symbols, allowing\r
+@cindex unresolved symbols, allowing\r
+@item -all-static\r
+If @var{output-file} is a program, then do not link it against any\r
+shared libraries at all. If @var{output-file} is a library, then only\r
+create a static library.\r
+\r
+@item -avoid-version\r
+Tries to avoid versioning (@pxref{Versioning}) for libraries and modules,\r
+i.e. no version information is stored and no symbolic links are created.\r
+If the platform requires versioning, this option has no effect.\r
+\r
+@item -dlopen @var{file}\r
+Same as @samp{-dlpreopen @var{file}}, if native dlopening is not\r
+supported on the host platform (@pxref{Dlopened modules}) or if\r
+the program is linked with @samp{-static} or @samp{-all-static}.\r
+Otherwise, no effect. If @var{file} is @code{self} libtool will make\r
+sure that the program can @code{dlopen} itself, either by enabling\r
+@code{-export-dynamic} or by falling back to @samp{-dlpreopen self}.\r
+\r
+@item -dlpreopen @var{file}\r
+Link @var{file} into the output program, and add its symbols to\r
+@var{lt_preloaded_symbols} (@pxref{Dlpreopening}). If @var{file} is\r
+@code{self}, the symbols of the program itself will be added to\r
+@var{lt_preloaded_symbols}.\r
+If @var{file} is @code{force} libtool will make sure that\r
+@var{lt_preloaded_symbols} is always @emph{defined}, regardless of whether\r
+it's empty or not.\r
+\r
+@item -export-dynamic\r
+Allow symbols from @var{output-file} to be resolved with @code{dlsym}\r
+(@pxref{Dlopened modules}).\r
+\r
+@item -export-symbols @var{symfile}\r
+Tells the linker to export only the symbols listed in @var{symfile}. \r
+The symbol file should end in @samp{.sym} and must contain the name of one \r
+symbol per line. This option has no effect on some platforms.\r
+By default all symbols are exported.\r
+\r
+@item -export-symbols-regex @var{regex}\r
+Same as @samp{-export-symbols}, except that only symbols matching\r
+the regular expression @var{regex} are exported.\r
+By default all symbols are exported.\r
+\r
+@item -L@var{libdir}\r
+Search @var{libdir} for required libraries that have already been\r
+installed.\r
+\r
+@item -l@var{name}\r
+@var{output-file} requires the installed library @file{lib@var{name}}.\r
+This option is required even when @var{output-file} is not an\r
+executable.\r
+\r
+@item -module\r
+Creates a library that can be dlopened (@pxref{Dlopened modules}). \r
+This option doesn't work for programs.\r
+Module names don't need to be prefixed with 'lib'.\r
+In order to prevent name clashes, however, 'libname' and 'name' \r
+must not be used at the same time in your package.\r
+\r
+@item -no-fast-install\r
+Disable fast-install mode for the executable @var{output-file}\r
+(@pxref{Invoking ltconfig}). Useful if the program won't be necessarly\r
+installed.\r
+\r
+@item -no-install\r
+Link an executable @var{output-file} (@pxref{Invoking ltconfig}) that\r
+can't be installed and therefore doesn't need a wrapper script.\r
+Useful if the program is only used in the build tree, e.g.,\r
+for testing or generating other files.\r
+\r
+@item -no-undefined\r
+Declare that @var{output-file} does not depend on any other libraries.\r
+Some platforms cannot create shared libraries that depend on other\r
+libraries (@pxref{Inter-library dependencies}).\r
+\r
+@item -o @var{output-file}\r
+Create @var{output-file} from the specified objects and libraries.\r
+\r
+@item -release @var{release}\r
+Specify that the library was generated by release @var{release} of your\r
+package, so that users can easily tell which versions are newer than\r
+others. Be warned that no two releases of your package will be binary\r
+compatible if you use this flag. If you want binary compatibility, use\r
+the @samp{-version-info} flag instead (@pxref{Versioning}).\r
+\r
+@item -rpath @var{libdir}\r
+If @var{output-file} is a library, it will eventually be installed in\r
+@var{libdir}. If @var{output-file} is a program, add @var{libdir} to\r
+the run-time path of the program.\r
+\r
+@item -R @var{libdir}\r
+If @var{output-file} is a program, add @var{libdir} to its run-time\r
+path. If @var{output-file} is a library, add -R@var{libdir} to its\r
+@var{dependency_libs}, so that, whenever the library is linked into a\r
+program, @var{libdir} will be added to its run-time path.\r
+\r
+@item -static\r
+If @var{output-file} is a program, then do not link it against any\r
+uninstalled shared libtool libraries. If @var{output-file} is a\r
+library, then only create a static library.\r
+\r
+@item -version-info @var{current}[:@var{revision}[:@var{age}]]\r
+If @var{output-file} is a libtool library, use interface version\r
+information @var{current}, @var{revision}, and @var{age} to build it\r
+(@pxref{Versioning}). Do @strong{not} use this flag to specify package\r
+release information, rather see the @samp{-release} flag.\r
+\r
+@item -Wl,@var{flag}\r
+@itemx -Xlinker @var{flag}\r
+Pass a linker specific flag directly to the linker.\r
+@end table\r
+\r
+If the @var{output-file} ends in @samp{.la}, then a libtool library is\r
+created, which must be built only from library objects (@samp{.lo} files).\r
+The @samp{-rpath} option is required. In the current implementation,\r
+libtool libraries may not depend on other uninstalled libtool libraries\r
+(@pxref{Inter-library dependencies}).\r
+\r
+If the @var{output-file} ends in @samp{.a}, then a standard library is\r
+created using @code{ar} and possibly @code{ranlib}.\r
+\r
+@cindex partial linking\r
+@cindex linking, partial\r
+If @var{output-file} ends in @samp{.o} or @samp{.lo}, then a reloadable object\r
+file is created from the input files (generally using @samp{ld -r}).\r
+This method is often called @dfn{partial linking}.\r
+\r
+Otherwise, an executable program is created.\r
+\r
+@node Execute mode\r
+@section Execute mode\r
+@cindex execute mode\r
+@cindex mode, execute\r
+\r
+For @dfn{execute} mode, the library path is automatically set, then a\r
+program is executed.\r
+\r
+The first of the @var{mode-args} is treated as a program name, with the\r
+rest as arguments to that program.\r
+\r
+The following components of @var{mode-args} are treated specially:\r
+\r
+@table @samp\r
+@item -dlopen @var{file}\r
+Add the directory containing @var{file} to the library path.\r
+@end table\r
+\r
+This mode sets the library path environment variable according to any\r
+@samp{-dlopen} flags.\r
+\r
+If any of the @var{args} are libtool executable wrappers, then they are\r
+translated into the name of their corresponding uninstalled binary, and\r
+any of their required library directories are added to the library path.\r
+\r
+@node Install mode\r
+@section Install mode\r
+@cindex install mode\r
+@cindex mode, install\r
+\r
+In @dfn{install} mode, libtool interprets @var{mode-args} as an\r
+installation command beginning with @code{cp}, or a BSD-compatible\r
+@code{install} program.\r
+\r
+The rest of the @var{mode-args} are interpreted as arguments to that\r
+command.\r
+\r
+The command is run, and any necessary unprivileged post-installation\r
+commands are also completed.\r
+\r
+@node Finish mode\r
+@section Finish mode\r
+@cindex finish mode\r
+@cindex mode, finish\r
+\r
+@dfn{Finish} mode helps system administrators install libtool libraries\r
+so that they can be located and linked into user programs.\r
+\r
+Each @var{mode-arg} is interpreted as the name of a library directory.\r
+Running this command may require superuser privileges, so the\r
+@samp{--dry-run} option may be useful.\r
+\r
+@node Uninstall mode\r
+@section Uninstall mode\r
+@cindex uninstall mode\r
+@cindex mode, uninstall\r
+\r
+@dfn{Uninstall} mode deletes installed libraries, executables and objects.\r
+\r
+The first @var{mode-arg} is the name of the program to use to delete\r
+files (typically @file{/bin/rm}).\r
+\r
+The remaining @var{mode-args} are either flags for the deletion program\r
+(beginning with a `-'), or the names of files to delete.\r
+\r
+@node Clean mode\r
+@section Clean mode\r
+@cindex clean mode\r
+@cindex mode, clean\r
+\r
+@dfn{Clean} mode deletes uninstalled libraries, executables, objects\r
+and libtool's temporary files associated with them.\r
+\r
+The first @var{mode-arg} is the name of the program to use to delete\r
+files (typically @file{/bin/rm}).\r
+\r
+The remaining @var{mode-args} are either flags for the deletion program\r
+(beginning with a `-'), or the names of files to delete.\r
+\r
+@node Integrating libtool\r
+@chapter Integrating libtool with your package\r
+\r
+This chapter describes how to integrate libtool with your packages so\r
+that your users can install hassle-free shared libraries.\r
+\r
+@menu\r
+* Makefile rules:: Writing @file{Makefile} rules for libtool.\r
+* Using Automake:: Automatically supporting libtool.\r
+* Configuring:: Configuring libtool for a host system.\r
+* Distributing:: What files to distribute with your package.\r
+* Static-only libraries:: Sometimes shared libraries are just a pain.\r
+@end menu\r
+\r
+@node Makefile rules\r
+@section Writing @file{Makefile} rules for libtool\r
+@cindex Makefile\r
+@cindex Makefile.am\r
+@cindex Makefile.in\r
+\r
+Libtool is fully integrated with Automake (@pxref{Top,, Introduction,\r
+automake, The Automake Manual}), starting with Automake version 1.2.\r
+\r
+If you want to use libtool in a regular @file{Makefile} (or\r
+@file{Makefile.in}), you are on your own. If you're not using Automake\r
+1.2, and you don't know how to incorporate libtool into your package you\r
+need to do one of the following:\r
+\r
+@enumerate 1\r
+@item\r
+Download Automake (version 1.2 or later) from your nearest GNU mirror,\r
+install it, and start using it.\r
+\r
+@item\r
+Learn how to write @file{Makefile} rules by hand. They're sometimes complex,\r
+but if you're clever enough to write rules for compiling your old\r
+libraries, then you should be able to figure out new rules for libtool\r
+libraries (hint: examine the @file{Makefile.in} in the @file{demo}\r
+subdirectory of the libtool distribution@dots{} note especially that it\r
+was automatically generated from the @file{Makefile.am} by Automake).\r
+@end enumerate\r
+\r
+@node Using Automake\r
+@section Using Automake with libtool\r
+\r
+@vindex LTLIBRARIES\r
+Libtool library support is implemented under the @samp{LTLIBRARIES}\r
+primary.\r
+\r
+Here are some samples from the Automake @file{Makefile.am} in the\r
+libtool distribution's @file{demo} subdirectory.\r
+\r
+First, to link a program against a libtool library, just use the\r
+@samp{program_LDADD} variable:\r
+\r
+@example\r
+bin_PROGRAMS = hell hell.debug\r
+\r
+# Build hell from main.c and libhello.la\r
+hell_SOURCES = main.c\r
+hell_LDADD = libhello.la\r
+\r
+# Create an easier-to-debug version of hell.\r
+hell_debug_SOURCES = main.c\r
+hell_debug_LDADD = libhello.la\r
+hell_debug_LDFLAGS = -static\r
+@end example\r
+\r
+The flags @samp{-dlopen} or @samp{-dlpreopen} (@pxref{Link mode}) would\r
+fit better in the @var{program_LDADD} variable. Unfortunately, GNU\r
+automake, up to release 1.4, doesn't accept these flags in a\r
+@var{program_LDADD} variable, so you have the following alternatives:\r
+\r
+@itemize @bullet\r
+@item\r
+add them to @var{program_LDFLAGS}, and list the libraries in\r
+@var{program_DEPENDENCIES}, then wait for a release of GNU automake that\r
+accepts these flags where they belong;\r
+\r
+@item\r
+surround the flags between quotes, but then you must set\r
+@var{program_DEPENDENCIES} too:\r
+\r
+@example\r
+program_LDADD = "-dlopen" libfoo.la\r
+program_DEPENDENCIES = libfoo.la\r
+@end example\r
+\r
+@item\r
+set and @samp{AC_SUBST} variables @var{DLOPEN} and @var{DLPREOPEN} in\r
+@file{configure.in} and use @samp{@@DLOPEN@@} and @samp{@@DLPREOPEN@@}\r
+as replacements for the explicit flags @samp{-dlopen} and\r
+@samp{-dlpreopen} in @samp{program_LDADD}. Automake will discard\r
+@samp{AC_SUBST}ed variables from dependencies, so it will behave exactly\r
+as we expect it to behave when it accepts these flags in\r
+@samp{program_LDADD}. But hey!, this is ugly!\r
+@end itemize\r
+\r
+You may use the @samp{program_LDFLAGS} variable to stuff in any flags\r
+you want to pass to libtool while linking @samp{program} (such as\r
+@samp{-static} to avoid linking uninstalled shared libtool libraries).\r
+\r
+Building a libtool library is almost as trivial@dots{} note the use of\r
+@samp{libhello_la_LDFLAGS} to pass the @samp{-version-info}\r
+(@pxref{Versioning}) option to libtool:\r
+\r
+@example\r
+# Build a libtool library, libhello.la for installation in libdir.\r
+lib_LTLIBRARIES = libhello.la\r
+libhello_la_SOURCES = hello.c foo.c\r
+libhello_la_LDFLAGS = -version-info 3:12:1\r
+@end example\r
+\r
+The @samp{-rpath} option is passed automatically by Automake (except for\r
+libraries listed as @code{noinst_LTLIBRARIES}), so you\r
+should not specify it.\r
+\r
+@xref{A Shared Library, Building a Shared Library, The Automake Manual,\r
+automake, The Automake Manual}, for more information.\r
+\r
+@node Configuring\r
+@section Configuring libtool\r
+@cindex configuring libtool\r
+\r
+Libtool requires intimate knowledge of your compiler suite and operating\r
+system in order to be able to create shared libraries and link against\r
+them properly. When you install the libtool distribution, a\r
+system-specific libtool script is installed into your binary directory.\r
+\r
+However, when you distribute libtool with your own packages\r
+(@pxref{Distributing}), you do not always know which compiler suite and\r
+operating system are used to compile your package.\r
+\r
+For this reason, libtool must be @dfn{configured} before it can be\r
+used. This idea should be familiar to anybody who has used a GNU\r
+@code{configure} script. @code{configure} runs a number of tests for\r
+system features, then generates the @file{Makefiles} (and possibly a\r
+@file{config.h} header file), after which you can run @code{make} and\r
+build the package.\r
+\r
+Libtool has its own equivalent to the @code{configure} script,\r
+@code{ltconfig}.\r
+\r
+@menu\r
+* Invoking ltconfig:: @code{ltconfig} command line options.\r
+* ltconfig example:: Manually configuring a @code{libtool}.\r
+* AM_PROG_LIBTOOL:: Configuring @code{libtool} in @file{configure.in}.\r
+@end menu\r
+\r
+@node Invoking ltconfig\r
+@subsection Invoking @code{ltconfig}\r
+@pindex ltconfig\r
+@cindex ltconfig command options\r
+@cindex options, ltconfig command\r
+@cindex command options, ltconfig\r
+\r
+@code{ltconfig} runs a series of configuration tests, then creates a\r
+system-specific @code{libtool} in the current directory. The\r
+@code{ltconfig} program has the following synopsis:\r
+\r
+@example\r
+ltconfig [@var{option}]@dots{} @var{ltmain} [@var{host}]\r
+@end example\r
+\r
+@noindent\r
+and accepts the following options:\r
+\r
+@table @samp\r
+@item --build=@var{build}\r
+Set the build system to be different to the host system. This creates a\r
+libtool which prefers build tools which are prefixed by the host alias over\r
+the standard tools. For example, specifying @code{--build=i486-pc-linux-gnu}\r
+on a host described by i486-pc-cygwin would create a libtool which used\r
+@code{i486-pc-cygwin-ranlib} in preference to @code{ranlib} if present. This\r
+is useful for cross build environments.\r
+\r
+@item --debug\r
+Dump a trace of shell script execution to standard output. This\r
+produces a lot of output, so you may wish to pipe it to @code{less} (or\r
+@code{more}) or redirect to a file.\r
+\r
+@item --disable-shared\r
+Create a @code{libtool} that only builds static libraries.\r
+\r
+@item --disable-static\r
+Create a @code{libtool} that builds only shared libraries if they are\r
+available. If only static libraries can be built, then this flag has\r
+no effect.\r
+\r
+@item --disable-fast-install\r
+On platforms in which installable executables, that are created by\r
+default, are not suitable for execution in the build directory, create a\r
+@code{libtool} that links executables that search for uninstalled\r
+libraries by default, and relinks them at install time. It is ignored\r
+on platforms in which a single executable is enough.\r
+\r
+@item --enable-dlopen\r
+Test whether some dlopening mechanism is supported. If this flag is not\r
+given, or no working dlopening mechanism is found, create a\r
+@code{libtool} that performs dlpreopening of all dlopened modules.\r
+\r
+@item --help\r
+Display a help message and exit.\r
+\r
+@item --no-verify\r
+Do not use @code{config.sub} to verify that @var{host} is a valid\r
+canonical host system name.\r
+\r
+@item --output=@var{file}\r
+@item -o @var{file}\r
+Instead of creating a libtool script called @code{libtool}, create one\r
+called @var{file}. This can be useful if you want to create libtool\r
+scripts for cross-compilers, or you want to have more than one libtool\r
+in the same directory.\r
+\r
+@item --quiet\r
+@itemx --silent\r
+Do not print informational messages when running configuration tests.\r
+\r
+@item --srcdir=@var{dir}\r
+Look for @code{config.guess} and @code{config.sub} in @var{dir}.\r
+\r
+@item --version\r
+Print @code{ltconfig} version information and exit.\r
+\r
+@item --add-tag=@var{tag}\r
+Instead of overwriting @code{libtool}, append a new configuration\r
+section to it, with the given @var{tag}.\r
+\r
+@item --with-gcc\r
+Assume that the GNU C compiler will be used when invoking the created\r
+@code{libtool} to compile and link object files.\r
+\r
+@item --with-gnu-ld\r
+Assume that the C compiler uses the GNU linker.\r
+\r
+@item --disable-lock\r
+Create a @code{libtool} that does not perform locking to ensure proper\r
+parallel compilation if the C compiler does not support @samp{-c} and\r
+@samp{-o} together.\r
+\r
+@item --cache-file=@var{file}\r
+Use this @var{file} as a cache for results of a few tests. This is\r
+usually @file{config.cache} used by @code{configure}. By default, no\r
+cache file is used.\r
+@end table\r
+\r
+@var{ltmain} is the @code{ltmain.sh} shell script fragment that provides\r
+the basic libtool functionality (@pxref{Distributing}).\r
+\r
+@var{host} is the canonical host system name, which by default is\r
+guessed by running @code{config.guess}.\r
+\r
+@code{ltconfig} also recognizes the following environment variables:\r
+\r
+@defvar CC\r
+The compiler that will be used by the generated @code{libtool}. If\r
+this is not set, @code{ltconfig} will look for @code{gcc} or @code{cc}.\r
+@end defvar\r
+\r
+@defvar LTCC\r
+A C compiler, in case @var{CC} is not one. If this is not set,\r
+@code{ltconfig} will use @var{CC} or extract @var{LTCC} from an existing\r
+@code{libtool}, if running in @samp{--add-tag} mode.\r
+@end defvar\r
+\r
+@defvar CFLAGS\r
+Compiler flags used to generate standard object files. If this is not\r
+set, @code{ltconfig} will not use any such flags. It affects only the\r
+way @code{ltconfig} runs tests, not the produced @code{libtool}.\r
+@end defvar\r
+\r
+@defvar CPPFLAGS\r
+C preprocessor flags. If this is not set, @code{ltconfig} will not use\r
+any such flags. It affects only the way @code{ltconfig} runs tests, not\r
+the produced @code{libtool}.\r
+@end defvar\r
+\r
+@defvar LD\r
+The system linker to use (if the generated @code{libtool} requires one).\r
+If this is not set, @code{ltconfig} will try to find out what is the\r
+linker used by @var{CC}.\r
+@end defvar\r
+\r
+@defvar LDFLAGS\r
+The flags to be used by @code{ltconfig} when it links a program. If\r
+this is not set, @code{ltconfig} will not use any such flags. It\r
+affects only the way @code{ltconfig} runs tests, not the produced\r
+@code{libtool}.\r
+@end defvar\r
+\r
+@defvar LIBS\r
+The libraries to be used by @code{ltconfig} when it links a program. If\r
+this is not set, @code{ltconfig} will not use any such flags. It\r
+affects only the way @code{ltconfig} runs tests, not the produced\r
+@code{libtool}.\r
+@end defvar\r
+\r
+@defvar NM\r
+Program to use rather than checking for @code{nm}.\r
+@end defvar\r
+\r
+@defvar RANLIB\r
+Program to use rather than checking for @code{ranlib}.\r
+@end defvar\r
+\r
+@defvar LN_S\r
+A command that creates a link of a program, a soft-link if possible, a\r
+hard-link otherwise.\r
+@end defvar\r
+\r
+@defvar DLLTOOL\r
+Program to use rather than checking for @code{dlltool}. Only meaningful \r
+for Cygwin/MS-Windows.\r
+@end defvar\r
+\r
+@defvar OBJDUMP\r
+Program to use rather than checking for @code{objdump}. Only meaningful \r
+for Cygwin/MS-Windows.\r
+@end defvar\r
+\r
+@defvar AS\r
+Program to use rather than checking for @code{as}. Only meaningful for\r
+Cygwin/MS-Windows.\r
+@end defvar\r
+\r
+@node ltconfig example\r
+@subsection Using @code{ltconfig}\r
+\r
+Here is a simple example of using @code{ltconfig} to configure libtool\r
+on a NetBSD/i386 1.2 system:\r
+\r
+@example\r
+burger$ @kbd{./ltconfig ltmain.sh}\r
+checking host system type... i386-unknown-netbsd1.2\r
+checking for ranlib... ranlib\r
+checking for gcc... gcc\r
+checking whether we are using GNU C... yes\r
+checking for gcc option to produce PIC... -fPIC -DPIC\r
+checking for gcc option to statically link programs... -static\r
+checking if ld is GNU ld... no\r
+checking if ld supports shared libraries... yes\r
+checking dynamic linker characteristics... netbsd1.2 ld.so\r
+checking if libtool supports shared libraries... yes\r
+checking whether to build shared libraries... yes\r
+creating libtool\r
+burger$\r
+@end example\r
+\r
+This example shows how to configure @code{libtool} for cross-compiling\r
+to a i486 GNU/Hurd 0.1 system (assuming compiler tools reside in\r
+@file{/local/i486-gnu/bin}):\r
+\r
+@example\r
+burger$ export PATH=/local/i486-gnu/bin:$PATH\r
+burger$ ./ltconfig ltmain.sh i486-gnu0.1\r
+checking host system type... i486-unknown-gnu0.1\r
+checking for ranlib... ranlib\r
+checking for gcc... gcc\r
+checking whether we are using GNU C... yes\r
+checking for gcc option to produce PIC... -fPIC -DPIC\r
+checking for gcc option to statically link programs... -static\r
+checking if ld is GNU ld... yes\r
+checking if GNU ld supports shared libraries... yes\r
+checking dynamic linker characteristics... gnu0.1 ld.so\r
+checking if libtool supports shared libraries... yes\r
+checking whether to build shared libraries... yes\r
+creating libtool\r
+burger$\r
+@end example\r
+\r
+@node AM_PROG_LIBTOOL\r
+@subsection The @code{AM_PROG_LIBTOOL} macro\r
+\r
+If you are using GNU Autoconf (or Automake), you should add a call to\r
+@code{AM_PROG_LIBTOOL} to your @file{configure.in} file. This macro\r
+offers seamless integration between the @code{configure} script and\r
+@code{ltconfig}:\r
+\r
+@defmac AM_PROG_LIBTOOL\r
+Add support for the @samp{--enable-shared} and @samp{--disable-shared}\r
+@code{configure} flags. Invoke @code{ltconfig} with the correct\r
+arguments to configure the package (@pxref{Invoking\r
+ltconfig}).@footnote{@code{AM_PROG_LIBTOOL} requires that you define the\r
+@file{Makefile} variable @code{top_builddir} in your @file{Makefile.in}.\r
+Automake does this automatically, but Autoconf users should set it to\r
+the relative path to the top of your build directory (@file{../..}, for\r
+example).}\r
+\r
+By default, this macro turns on shared libraries if they are available,\r
+and also enables static libraries if they don't conflict with the shared\r
+libraries. You can modify these defaults by calling either the\r
+@code{AC_DISABLE_SHARED} or @code{AC_DISABLE_STATIC} macros:\r
+\r
+@example\r
+# Turn off shared libraries during beta-testing, since they\r
+# make the build process take too long.\r
+AC_DISABLE_SHARED\r
+AM_PROG_LIBTOOL\r
+@end example\r
+\r
+The user may specify modified forms of the configure flags\r
+@samp{--enable-shared} and @samp{--enable-static} to choose whether\r
+shared or static libraries are built based on the name of the package.\r
+For example, to have shared @samp{bfd} and @samp{gdb} libraries built,\r
+but not shared @samp{libg++}, you can run all three @code{configure}\r
+scripts as follows:\r
+\r
+@example\r
+trick$ ./configure --enable-shared=bfd,gdb\r
+@end example\r
+\r
+In general, specifying @samp{--enable-shared=@var{pkgs}} is the same as\r
+configuring with @samp{--enable-shared} every package named in the\r
+comma-separated @var{pkgs} list, and every other package with\r
+@samp{--disable-shared}. The @samp{--enable-static=@var{pkgs}} flag\r
+behaves similarly, but it uses @samp{--enable-static} and\r
+@samp{--disable-static}. The same applies to the \r
+@samp{--enable-fast-install=@var{pkgs}} flag, which uses\r
+@samp{--enable-fast-install} and @samp{--disable-fast-install}.\r
+\r
+The package name @samp{default} matches any packages which have not set\r
+their name in the @code{PACKAGE} environment variable.\r
+\r
+This macro also sets the shell variable @var{LIBTOOL_DEPS}, that you can \r
+use to automatically update the libtool script if it becomes\r
+out-of-date. In order to do that, add to your @file{configure.in}:\r
+\r
+@example\r
+AM_PROG_LIBTOOL\r
+AC_SUBST(LIBTOOL_DEPS)\r
+@end example\r
+\r
+and, to @file{Makefile.in} or @file{Makefile.am}:\r
+\r
+@example\r
+LIBTOOL_DEPS = @@LIBTOOL_DEPS@@\r
+libtool: $(LIBTOOL_DEPS)\r
+ $(SHELL) ./config.status --recheck\r
+@end example\r
+\r
+If you are using GNU automake, you can omit the assignment, as automake\r
+will take care of it. You'll obviously have to create some dependency\r
+on @file{libtool}.\r
+\r
+@end defmac\r
+\r
+@defmac AC_LIBTOOL_CXX\r
+Enable C++ shared library support. This macro should be used if libtool\r
+will be used to generate C++ shared libraries. It causes a C++-specific\r
+configuration to be appended to the @file{libtool} script. The C++\r
+support can coexist with other configurations, including the default C\r
+shared library configuration. It is not necessary to invoke this macro\r
+explicitly, as long as @code{AC_PROG_CXX} is called within the configure\r
+script.\r
+@end defmac\r
+\r
+@defmac AC_LIBTOOL_GCJ\r
+Enable GCJ shared library support. This macro should be used if libtool\r
+will be used to generate GCJ shared libraries. It causes a GCJ-specific\r
+configuration to be appended to the @file{libtool} script. The GCJ\r
+support can coexist with other configurations, including the default C\r
+shared library configuration. It is not necessary to invoke this macro\r
+explicitly, as long as @code{AM_PROG_GCJ} (or @code{AC_PROG_GCJ},\r
+whenever it is implemented in autoconf) is called within the configure\r
+script.\r
+@end defmac\r
+\r
+@defmac AC_LIBTOOL_DLOPEN\r
+Enable checking for dlopen support. This macro should be used if\r
+the package makes use of the @samp{-dlopen} and @samp{-dlpreopen} flags,\r
+otherwise libtool will assume that the system does not support dlopening.\r
+The macro must be called @strong{before} @code{AM_PROG_LIBTOOL}.\r
+@end defmac\r
+\r
+@defmac AC_LIBTOOL_WIN32_DLL\r
+This macro should be used if the package has been ported to build clean\r
+dlls on win32 platforms. Usually this means that any library data items\r
+are exported with @code{__declspec(dllexport)} and imported with\r
+@code{__declspec(dllimport)}. If this macro is not used, libtool will\r
+assume that the package libraries are not dll clean and will build only\r
+static libraries on win32 hosts.\r
+\r
+@code{AM_PROG_LIBTOOL} must be called @strong{after} this macro, and\r
+provision must be made to pass @samp{-no-undefined} to @code{libtool}\r
+in link mode from the package @code{Makefile}. Naturally, passing\r
+@samp{-no-undefined} means that all the library symbols @strong{really are}\r
+defined at link time!\r
+@end defmac\r
+\r
+@defmac AC_DISABLE_FAST_INSTALL\r
+Change the default behaviour for @code{AM_PROG_LIBTOOL} to disable\r
+optimization for fast installation. The user may still override this\r
+default, depending on platform support, by specifying\r
+@samp{--enable-fast-install}.\r
+@end defmac\r
+\r
+@defmac AC_DISABLE_SHARED\r
+@defmacx AM_DISABLE_SHARED\r
+Change the default behaviour for @code{AM_PROG_LIBTOOL} to disable\r
+shared libraries. The user may still override this default by\r
+specifying @samp{--enable-shared}.\r
+@end defmac\r
+\r
+@defmac AC_DISABLE_STATIC\r
+@defmacx AM_DISABLE_STATIC\r
+Change the default behaviour for @code{AM_PROG_LIBTOOL} to disable\r
+static libraries. The user may still override this default by\r
+specifying @samp{--enable-static}.\r
+@end defmac\r
+\r
+@pindex aclocal\r
+When you invoke the @code{libtoolize} program (@pxref{Invoking\r
+libtoolize}), it will tell you where to find a definition of\r
+@code{AM_PROG_LIBTOOL}. If you use Automake, the @code{aclocal} program\r
+will automatically add @code{AM_PROG_LIBTOOL} support to your\r
+@code{configure} script.\r
+\r
+Nevertheless, it is advisable to include a copy of @file{libtool.m4} in\r
+@file{acinclude.m4}, so that, even if @file{aclocal.m4} and\r
+@file{configure} are rebuilt for any reason, the appropriate libtool\r
+macros will be used. The alternative is to hope the user will have a\r
+compatible version of @file{libtool.m4} installed and accessible for\r
+@code{aclocal}. This may lead to weird errors when versions don't\r
+match.\r
+\r
+@node Distributing\r
+@section Including libtool in your package\r
+\r
+In order to use libtool, you need to include the following files with\r
+your package:\r
+\r
+@table @file\r
+@item config.guess\r
+@pindex config.guess\r
+Attempt to guess a canonical system name.\r
+\r
+@item config.sub\r
+@pindex config.sub\r
+Canonical system name validation subroutine script.\r
+\r
+@item ltconfig\r
+Generate a libtool script for a given system.\r
+\r
+@item ltmain.sh\r
+@pindex ltmain.sh\r
+A generic script implementing basic libtool functionality.\r
+@end table\r
+\r
+Note that the libtool script itself should @emph{not} be included with\r
+your package. @xref{Configuring}.\r
+\r
+You should use the @code{libtoolize} program, rather than manually\r
+copying these files into your package.\r
+\r
+@menu\r
+* Invoking libtoolize:: @code{libtoolize} command line options.\r
+* Autoconf .o macros:: Autoconf macros that set object file names.\r
+@end menu\r
+\r
+@node Invoking libtoolize\r
+@subsection Invoking @code{libtoolize}\r
+@pindex libtoolize\r
+@cindex libtoolize command options\r
+@cindex command options, libtoolize\r
+@cindex options, libtoolize command\r
+\r
+The @code{libtoolize} program provides a standard way to add libtool\r
+support to your package. In the future, it may implement better usage\r
+checking, or other features to make libtool even easier to use.\r
+\r
+The @code{libtoolize} program has the following synopsis:\r
+\r
+@example\r
+libtoolize [@var{option}]@dots{}\r
+@end example\r
+\r
+@noindent\r
+and accepts the following options:\r
+\r
+@table @samp\r
+@item --automake\r
+Work silently, and assume that Automake libtool support is used.\r
+\r
+@samp{libtoolize --automake} is used by Automake to add libtool files to\r
+your package, when @code{AM_PROG_LIBTOOL} appears in your\r
+@file{configure.in}.\r
+\r
+@item --copy\r
+@itemx -c\r
+Copy files from the libtool data directory rather than creating\r
+symlinks.\r
+\r
+@item --debug\r
+Dump a trace of shell script execution to standard output. This\r
+produces a lot of output, so you may wish to pipe it to @code{less} (or\r
+@code{more}) or redirect to a file.\r
+\r
+@item --dry-run\r
+@itemx -n\r
+Don't run any commands that modify the file system, just print them\r
+out.\r
+\r
+@item --force\r
+@itemx -f\r
+Replace existing libtool files. By default, @code{libtoolize} won't\r
+overwrite existing files.\r
+\r
+@item --help\r
+Display a help message and exit.\r
+\r
+@item --ltdl\r
+Install libltdl in a subdirectory of your package.\r
+\r
+@item --ltdl-tar\r
+Add the file libltdl.tar.gz to your package.\r
+\r
+@item --version\r
+Print @code{libtoolize} version information and exit.\r
+@end table\r
+\r
+@findex AC_CONFIG_AUX_DIR\r
+If @code{libtoolize} detects an explicit call to\r
+@code{AC_CONFIG_AUX_DIR} (@pxref{Input, , The Autoconf Manual,\r
+autoconf, The Autoconf Manual}) in your @file{configure.in}, it\r
+will put the files in the specified directory.\r
+\r
+@code{libtoolize} displays hints for adding libtool support to your\r
+package, as well.\r
+\r
+@node Autoconf .o macros\r
+@subsection Autoconf @samp{.o} macros\r
+\r
+The Autoconf package comes with a few macros that run tests, then set a\r
+variable corresponding to the name of an object file. Sometimes it is\r
+necessary to use corresponding names for libtool objects.\r
+\r
+Here are the names of variables that list libtool objects:\r
+\r
+@defvar LTALLOCA\r
+@findex AC_FUNC_ALLOCA\r
+Substituted by @code{AC_FUNC_ALLOCA} (@pxref{Particular Functions, Particular\r
+Function Checks, The Autoconf Manual, autoconf, The Autoconf\r
+Manual}). Is either empty, or contains @samp{alloca.lo}.\r
+@end defvar\r
+\r
+@defvar LTLIBOBJS\r
+@findex AC_REPLACE_FUNCS\r
+Substituted by @code{AC_REPLACE_FUNCS} (@pxref{Generic Functions, Generic\r
+Function Checks, The Autoconf Manual, autoconf, The Autoconf\r
+Manual}), and a few other functions.\r
+@end defvar\r
+\r
+Unfortunately, the most recent version of Autoconf (2.12, at the time of\r
+this writing) does not have any way for libtool to provide support for\r
+these variables. So, if you depend on them, use the following code\r
+immediately before the call to @code{AC_OUTPUT} in your\r
+@file{configure.in}:\r
+\r
+@example\r
+LTLIBOBJS=`echo "$LIBOBJS" | sed 's/\.o/.lo/g'`\r
+AC_SUBST(LTLIBOBJS)\r
+LTALLOCA=`echo "$ALLOCA" | sed 's/\.o/.lo/g'`\r
+AC_SUBST(LTALLOCA)\r
+AC_OUTPUT(@dots{})\r
+@end example\r
+\r
+@node Static-only libraries\r
+@section Static-only libraries\r
+@cindex debugging libraries\r
+@cindex developing libraries\r
+@cindex double-compilation, avoiding\r
+@cindex avoiding shared libraries\r
+@cindex eliding shared libraries\r
+@cindex using shared libraries, not\r
+@cindex shared libraries, not using\r
+@cindex time, saving\r
+@cindex saving time\r
+\r
+When you are developing a package, it is often worthwhile to configure\r
+your package with the @samp{--disable-shared} flag, or to override the\r
+defaults for @code{AM_PROG_LIBTOOL} by using the\r
+@code{AM_DISABLE_SHARED} Autoconf macro (@pxref{AM_PROG_LIBTOOL, , The\r
+@code{AM_PROG_LIBTOOL} macro}). This prevents libtool from building\r
+shared libraries, which has several advantages:\r
+\r
+@itemize @bullet\r
+@item\r
+compilation is twice as fast, which can speed up your development cycle,\r
+\r
+@item\r
+debugging is easier because you don't need to deal with any complexities\r
+added by shared libraries, and\r
+\r
+@item\r
+you can see how libtool behaves on static-only platforms.\r
+@end itemize\r
+\r
+You may want to put a small note in your package @file{README} to let\r
+other developers know that @samp{--disable-shared} can save them time.\r
+The following example note is taken from the GIMP@footnote{GNU Image\r
+Manipulation Program, for those who haven't taken the plunge. See\r
+@url{http://www.gimp.org/}.} distribution @file{README}:\r
+\r
+@example\r
+The GIMP uses GNU Libtool in order to build shared libraries on a\r
+variety of systems. While this is very nice for making usable\r
+binaries, it can be a pain when trying to debug a program. For that\r
+reason, compilation of shared libraries can be turned off by\r
+specifying the @samp{--disable-shared} option to @file{configure}.\r
+@end example\r
+\r
+@node Versioning\r
+@chapter Library interface versions\r
+@cindex dynamic dependencies\r
+@cindex dependency versioning\r
+@cindex shared library versions\r
+\r
+The most difficult issue introduced by shared libraries is that of\r
+creating and resolving runtime dependencies. Dependencies on programs\r
+and libraries are often described in terms of a single name, such as\r
+@code{sed}. So, one may say ``libtool depends on sed,'' and that is\r
+good enough for most purposes.\r
+\r
+However, when an interface changes regularly, we need to be more\r
+specific: ``Gnus 5.1 requires Emacs 19.28 or above.'' Here, the\r
+description of an interface consists of a name, and a ``version\r
+number.''\r
+\r
+Even that sort of description is not accurate enough for some purposes.\r
+What if Emacs 20 changes enough to break Gnus 5.1?\r
+\r
+The same problem exists in shared libraries: we require a formal version\r
+system to describe the sorts of dependencies that programs have on\r
+shared libraries, so that the dynamic linker can guarantee that programs\r
+are linked only against libraries that provide the interface they\r
+require.\r
+\r
+@menu\r
+* Interfaces:: What are library interfaces?\r
+* Libtool versioning:: Libtool's versioning system.\r
+* Updating version info:: Changing version information before releases.\r
+* Release numbers:: Breaking binary compatibility for aesthetics.\r
+@end menu\r
+\r
+@node Interfaces\r
+@section What are library interfaces?\r
+@cindex library interfaces\r
+\r
+Interfaces for libraries may be any of the following (and more):\r
+\r
+@itemize @bullet\r
+@item\r
+global variables: both names and types\r
+\r
+@item\r
+global functions: argument types and number, return types, and function names\r
+\r
+@item\r
+standard input, standard output, standard error, and file formats\r
+\r
+@item\r
+sockets, pipes, and other inter-process communication protocol formats\r
+@end itemize\r
+\r
+Note that static functions do not count as interfaces, because they are\r
+not directly available to the user of the library.\r
+\r
+@node Libtool versioning\r
+@section Libtool's versioning system\r
+@cindex libtool library versions\r
+@cindex formal versioning\r
+@cindex versioning, formal\r
+\r
+Libtool has its own formal versioning system. It is not as flexible as\r
+some, but it is definitely the simplest of the more powerful versioning\r
+systems.\r
+\r
+Think of a library as exporting several sets of interfaces, arbitrarily\r
+represented by integers. When a program is linked against a library, it\r
+may use any subset of those interfaces.\r
+\r
+Libtool's description of the interfaces that a program uses is simple:\r
+it encodes the least and the greatest interface numbers in the resulting\r
+binary (@var{first-interface}, @var{last-interface}).\r
+\r
+The dynamic linker is guaranteed that if a library supports @emph{every}\r
+interface number between @var{first-interface} and @var{last-interface},\r
+then the program can be relinked against that library.\r
+\r
+Note that this can cause problems because libtool's compatibility\r
+requirements are actually stricter than is necessary.\r
+\r
+Say @file{libhello} supports interfaces 5, 16, 17, 18, and 19, and that\r
+libtool is used to link @file{test} against @file{libhello}.\r
+\r
+Libtool encodes the numbers 5 and 19 in @file{test}, and the dynamic\r
+linker will only link @file{test} against libraries that support\r
+@emph{every} interface between 5 and 19. So, the dynamic linker refuses\r
+to link @file{test} against @file{libhello}!\r
+\r
+In order to eliminate this problem, libtool only allows libraries to\r
+declare consecutive interface numbers. So, @file{libhello} can declare at\r
+most that it supports interfaces 16 through 19. Then, the dynamic\r
+linker will link @file{test} against @file{libhello}.\r
+\r
+So, libtool library versions are described by three integers:\r
+\r
+@table @var\r
+@item current\r
+The most recent interface number that this library implements.\r
+\r
+@item revision\r
+The implementation number of the @var{current} interface.\r
+\r
+@item age\r
+The difference between the newest and oldest interfaces that this\r
+library implements. In other words, the library implements all the\r
+interface numbers in the range from number @code{@var{current} -\r
+@var{age}} to @code{@var{current}}.\r
+@end table\r
+\r
+If two libraries have identical @var{current} and @var{age} numbers,\r
+then the dynamic linker chooses the library with the greater\r
+@var{revision} number.\r
+\r
+@node Updating version info\r
+@section Updating library version information\r
+\r
+If you want to use libtool's versioning system, then you must specify\r
+the version information to libtool using the @samp{-version-info} flag\r
+during link mode (@pxref{Link mode}).\r
+\r
+This flag accepts an argument of the form\r
+@samp{@var{current}[:@var{revision}[:@var{age}]]}. So, passing\r
+@samp{-version-info 3:12:1} sets @var{current} to 3, @var{revision} to\r
+12, and @var{age} to 1.\r
+\r
+If either @var{revision} or @var{age} are omitted, they default to 0.\r
+Also note that @var{age} must be less than or equal to the @var{current}\r
+interface number.\r
+\r
+Here are a set of rules to help you update your library version\r
+information:\r
+\r
+@enumerate 1\r
+@item\r
+Start with version information of @samp{0:0:0} for each libtool library.\r
+\r
+@item\r
+Update the version information only immediately before a public release\r
+of your software. More frequent updates are unnecessary, and only\r
+guarantee that the current interface number gets larger faster.\r
+\r
+@item\r
+If the library source code has changed at all since the last update,\r
+then increment @var{revision} (@samp{@var{c}:@var{r}:@var{a}} becomes\r
+@samp{@var{c}:@math{r+1}:@var{a}}).\r
+\r
+@item\r
+If any interfaces have been added, removed, or changed since the last\r
+update, increment @var{current}, and set @var{revision} to 0.\r
+\r
+@item\r
+If any interfaces have been added since the last public release, then\r
+increment @var{age}.\r
+\r
+@item\r
+If any interfaces have been removed since the last public release, then\r
+set @var{age} to 0.\r
+@end enumerate\r
+\r
+@strong{@emph{Never}} try to set the interface numbers so that they\r
+correspond to the release number of your package. This is an abuse that\r
+only fosters misunderstanding of the purpose of library versions.\r
+Instead, use the @samp{-release} flag (@pxref{Release numbers}), but be\r
+warned that every release of your package will not be binary compatible\r
+with any other release.\r
+\r
+@node Release numbers\r
+@section Managing release information\r
+\r
+Often, people want to encode the name of the package release into the\r
+shared library so that it is obvious to the user which package their\r
+programs are linked against. This convention is used especially on\r
+GNU/Linux:\r
+\r
+@example\r
+trick$ @kbd{ls /usr/lib/libbfd*}\r
+/usr/lib/libbfd.a /usr/lib/libbfd.so.2.7.0.2\r
+/usr/lib/libbfd.so\r
+trick$\r
+@end example\r
+\r
+On @samp{trick}, @file{/usr/lib/libbfd.so} is a symbolic link to\r
+@file{libbfd.so.2.7.0.2}, which was distributed as a part of\r
+@samp{binutils-2.7.0.2}.\r
+\r
+Unfortunately, this convention conflicts directly with libtool's idea of\r
+library interface versions, because the library interface rarely changes\r
+at the same time that the release number does, and the library suffix is\r
+never the same across all platforms.\r
+\r
+So, in order to accommodate both views, you can use the @samp{-release}\r
+flag in order to set release information for libraries which you do not\r
+want to use @samp{-version-info}. For the @file{libbfd} example, the\r
+next release which uses libtool should be built with @samp{-release\r
+2.9.0}, which will produce the following files on GNU/Linux:\r
+\r
+@example\r
+trick$ @kbd{ls /usr/lib/libbfd*}\r
+/usr/lib/libbfd-2.9.0.so /usr/lib/libbfd.a\r
+/usr/lib/libbfd.so\r
+trick$\r
+@end example\r
+\r
+In this case, @file{/usr/lib/libbfd.so} is a symbolic link to\r
+@file{libbfd-2.9.0.so}. This makes it obvious that the user is dealing\r
+with @samp{binutils-2.9.0}, without compromising libtool's idea of\r
+interface versions.\r
+\r
+Note that this option causes a modification of the library name, so do\r
+not use it unless you want to break binary compatibility with any past\r
+library releases. In general, you should only use @samp{-release} for\r
+package-internal libraries or for ones whose interfaces change very\r
+frequently.\r
+\r
+@node Library tips\r
+@chapter Tips for interface design\r
+@cindex library interfaces, design\r
+@cindex design of library interfaces\r
+\r
+Writing a good library interface takes a lot of practice and thorough\r
+understanding of the problem that the library is intended to solve.\r
+\r
+If you design a good interface, it won't have to change often, you won't\r
+have to keep updating documentation, and users won't have to keep\r
+relearning how to use the library.\r
+\r
+Here is a brief list of tips for library interface design, which may\r
+help you in your exploits:\r
+\r
+@table @asis\r
+@item Plan ahead\r
+Try to make every interface truly minimal, so that you won't need to\r
+delete entry points very often.\r
+\r
+@item Avoid interface changes\r
+@cindex renaming interface functions\r
+Some people love redesigning and changing entry points just for the heck\r
+of it (note: @emph{renaming} a function is considered changing an entry\r
+point). Don't be one of those people. If you must redesign an\r
+interface, then try to leave compatibility functions behind so that\r
+users don't need to rewrite their existing code.\r
+\r
+@item Use opaque data types\r
+@cindex opaque data types\r
+The fewer data type definitions a library user has access to, the\r
+better. If possible, design your functions to accept a generic pointer\r
+(which you can cast to an internal data type), and provide access\r
+functions rather than allowing the library user to directly manipulate\r
+the data.\r
+That way, you have the freedom to change the data structures without\r
+changing the interface.\r
+\r
+This is essentially the same thing as using abstract data types and\r
+inheritance in an object-oriented system.\r
+\r
+@item Use header files\r
+@cindex header files\r
+If you are careful to document each of your library's global functions\r
+and variables in header files, and include them in your library source\r
+files, then the compiler will let you know if you make any interface\r
+changes by accident (@pxref{C header files}).\r
+\r
+@item Use the @code{static} keyword (or equivalent) whenever possible\r
+@cindex global functions\r
+The fewer global functions your library has, the more flexibility you'll\r
+have in changing them. Static functions and variables may change forms\r
+as often as you like@dots{} your users cannot access them, so they\r
+aren't interface changes.\r
+@end table\r
+\r
+@menu\r
+* C header files:: How to write portable include files.\r
+@end menu\r
+\r
+@node C header files\r
+@section Writing C header files\r
+@cindex portable C headers\r
+@cindex C header files, portable\r
+@cindex include files, portable\r
+\r
+Writing portable C header files can be difficult, since they may be read\r
+by different types of compilers:\r
+\r
+@table @asis\r
+@item C++ compilers\r
+C++ compilers require that functions be declared with full prototypes,\r
+since C++ is more strongly typed than C. C functions and variables also\r
+need to be declared with the @code{extern "C"} directive, so that the\r
+names aren't mangled. @xref{C++ libraries}, for other issues relevant\r
+to using C++ with libtool.\r
+\r
+@item ANSI C compilers\r
+ANSI C compilers are not as strict as C++ compilers, but functions\r
+should be prototyped to avoid unnecessary warnings when the header file\r
+is @code{#include}d.\r
+\r
+@item non-ANSI C compilers\r
+Non-ANSI compilers will report errors if functions are prototyped.\r
+@end table\r
+\r
+These complications mean that your library interface headers must use\r
+some C preprocessor magic in order to be usable by each of the above\r
+compilers.\r
+\r
+@file{foo.h} in the @file{demo} subdirectory of the libtool distribution\r
+serves as an example for how to write a header file that can be\r
+safely installed in a system directory.\r
+\r
+Here are the relevant portions of that file:\r
+\r
+@example\r
+/* __BEGIN_DECLS should be used at the beginning of your declarations,\r
+ so that C++ compilers don't mangle their names. Use __END_DECLS at\r
+ the end of C declarations. */\r
+#undef __BEGIN_DECLS\r
+#undef __END_DECLS\r
+#ifdef __cplusplus\r
+# define __BEGIN_DECLS extern "C" @{\r
+# define __END_DECLS @}\r
+#else\r
+# define __BEGIN_DECLS /* empty */\r
+# define __END_DECLS /* empty */\r
+#endif\r
+\r
+/* __P is a macro used to wrap function prototypes, so that compilers\r
+ that don't understand ANSI C prototypes still work, and ANSI C\r
+ compilers can issue warnings about type mismatches. */\r
+#undef __P\r
+#if defined (__STDC__) || defined (_AIX) \\r
+ || (defined (__mips) && defined (_SYSTYPE_SVR4)) \\r
+ || defined(WIN32) || defined(__cplusplus)\r
+# define __P(protos) protos\r
+#else\r
+# define __P(protos) ()\r
+#endif\r
+@end example\r
+\r
+These macros are used in @file{foo.h} as follows:\r
+\r
+@example\r
+#ifndef _FOO_H_\r
+#define _FOO_H_ 1\r
+\r
+/* The above macro definitions. */\r
+@dots{}\r
+\r
+__BEGIN_DECLS\r
+int foo __P((void));\r
+int hello __P((void));\r
+__END_DECLS\r
+\r
+#endif /* !_FOO_H_ */\r
+@end example\r
+\r
+Note that the @file{#ifndef _FOO_H_} prevents the body of @file{foo.h}\r
+from being read more than once in a given compilation.\r
+\r
+Feel free to copy the definitions of @code{__P}, @code{__BEGIN_DECLS},\r
+and @code{__END_DECLS} into your own headers. Then, you may use them to\r
+create header files that are valid for C++, ANSI, and non-ANSI\r
+compilers.\r
+\r
+Do not be naive about writing portable code. Following the tips given\r
+above will help you miss the most obvious problems, but there are\r
+definitely other subtle portability issues. You may need to cope with\r
+some of the following issues:\r
+\r
+@itemize @bullet\r
+@item\r
+Pre-ANSI compilers do not always support the @code{void *} generic\r
+pointer type, and so need to use @code{char *} in its place.\r
+\r
+@item\r
+The @code{const} and @code{signed} keywords are not supported by some\r
+compilers, especially pre-ANSI compilers.\r
+\r
+@item\r
+The @code{long double} type is not supported by many compilers.\r
+@end itemize\r
+\r
+@node Inter-library dependencies\r
+@chapter Inter-library dependencies\r
+@cindex dependencies between libraries\r
+@cindex inter-library dependencies\r
+\r
+By definition, every shared library system provides a way for\r
+executables to depend on libraries, so that symbol resolution is\r
+deferred until runtime.\r
+\r
+An @dfn{inter-library dependency} is one in which a library depends on\r
+other libraries. For example, if the libtool library @file{libhello}\r
+uses the @code{cos} function, then it has an inter-library dependency\r
+on @file{libm}, the math library that implements @code{cos}.\r
+\r
+Some shared library systems provide this feature in an\r
+internally-consistent way: these systems allow chains of dependencies of\r
+potentially infinite length.\r
+\r
+However, most shared library systems are restricted in that they only\r
+allow a single level of dependencies. In these systems, programs may\r
+depend on shared libraries, but shared libraries may not depend on other\r
+shared libraries.\r
+\r
+In any event, libtool provides a simple mechanism for you to declare\r
+inter-library dependencies: for every library @file{lib@var{name}} that\r
+your own library depends on, simply add a corresponding\r
+@code{-l@var{name}} option to the link line when you create your\r
+library. To make an example of our\r
+@file{libhello} that depends on @file{libm}:\r
+\r
+@example\r
+burger$ @kbd{libtool gcc -g -O -o libhello.la foo.lo hello.lo \\r
+ -rpath /usr/local/lib -lm}\r
+burger$\r
+@end example\r
+\r
+When you link a program against @file{libhello}, you don't need to\r
+specify the same @samp{-l} options again: libtool will do that for you,\r
+in order to guarantee that all the required libraries are found. This\r
+restriction is only necessary to preserve compatibility with static\r
+library systems and simple dynamic library systems.\r
+\r
+Some platforms, such as AIX, do not even allow you this\r
+flexibility. In order to build a shared library, it must be entirely\r
+self-contained (that is, have references only to symbols that are found\r
+in the @samp{.lo} files or the specified @samp{-l} libraries), and you\r
+need to specify the @var{-no-undefined} flag. By default, libtool\r
+builds only static libraries on these kinds of platforms.\r
+\r
+The simple-minded inter-library dependency tracking code of libtool\r
+releases prior to 1.2 was disabled because it was not clear when it was\r
+possible to link one library with another, and complex failures would\r
+occur. A more complex implementation of this concept was re-introduced\r
+before release 1.3, but it has not been ported to all platforms that\r
+libtool supports. The default, conservative behavior is to avoid\r
+linking one library with another, introducing their inter-dependencies\r
+only when a program is linked with them.\r
+\r
+@node Dlopened modules\r
+@chapter Dlopened modules\r
+@findex dlopen\r
+@findex dlsym\r
+@findex dlclose\r
+@findex shl_load\r
+@cindex dynamic linking, applications\r
+@cindex dlopening modules\r
+@cindex modules, dynamic\r
+@cindex application-level dynamic linking\r
+\r
+It can sometimes be confusing to discuss @dfn{dynamic linking}, because\r
+the term is used to refer to two different concepts:\r
+\r
+@enumerate 1\r
+@item\r
+Compiling and linking a program against a shared library, which is\r
+resolved automatically at run time by the dynamic linker. In this\r
+process, dynamic linking is transparent to the application.\r
+\r
+@item\r
+The application calling functions such as @code{dlopen},@footnote{HP-UX,\r
+to be different, uses a function named @code{shl_load}.} which load\r
+arbitrary, user-specified modules at runtime. This type of dynamic\r
+linking is explicitly controlled by the application.\r
+@end enumerate\r
+\r
+To mitigate confusion, this manual refers to the second type of dynamic\r
+linking as @dfn{dlopening} a module.\r
+\r
+The main benefit to dlopening object modules is the ability to access\r
+compiled object code to extend your program, rather than using an\r
+interpreted language. In fact, dlopen calls are frequently used in\r
+language interpreters to provide an efficient way to extend the\r
+language.\r
+\r
+As of version @value{VERSION}, libtool provides support for dlopened\r
+modules. However, you should indicate that your package is willing to\r
+use such support, by using the macro @samp{AC_LIBTOOL_DLOPEN} in\r
+@file{configure.in}. If this macro is not used (or it is used\r
+@emph{after} @samp{AM_PROG_LIBTOOL}), libtool will assume no dlopening\r
+mechanism is available, and will try to simulate it.\r
+\r
+This chapter discusses how you as a dlopen application developer might \r
+use libtool to generate dlopen-accessible modules.\r
+\r
+@menu\r
+* Building modules:: Creating dlopenable objects and libraries.\r
+* Dlpreopening:: Dlopening that works on static platforms.\r
+* Finding the dlname:: Choosing the right file to @code{dlopen}.\r
+* Dlopen issues:: Unresolved problems that need your attention.\r
+@end menu\r
+\r
+@node Building modules\r
+@section Building modules to dlopen\r
+\r
+On some operating systems, a program symbol must be specially declared\r
+in order to be dynamically resolved with the @code{dlsym} (or\r
+equivalent) function.\r
+\r
+Libtool provides the @samp{-export-dynamic} and @samp{-module} \r
+link flags (@pxref{Link mode}), which do this declaration. \r
+You need to use these flags if you are linking an application program that \r
+dlopens other modules or a libtool library that will also be dlopened.\r
+\r
+For example, if we wanted to build a shared library, @file{libhello},\r
+that would later be dlopened by an application, we would add\r
+@samp{-module} to the other link flags:\r
+\r
+@example\r
+burger$ @kbd{libtool gcc -module -o libhello.la foo.lo \\r
+ hello.lo -rpath /usr/local/lib -lm}\r
+burger$\r
+@end example\r
+\r
+If symbols from your @emph{executable} are needed to satisfy unresolved\r
+references in a library you want to dlopen you will have to use the flag\r
+@samp{-export-dynamic}.\r
+You should use @samp{-export-dynamic} while linking the executable that calls\r
+dlopen:\r
+\r
+@example\r
+burger$ @kbd{libtool gcc -export-dynamic -o hell-dlopener main.o}\r
+burger$\r
+@end example\r
+\r
+@node Dlpreopening\r
+@section Dlpreopening\r
+\r
+Libtool provides special support for dlopening libtool object and\r
+libtool library files, so that their symbols can be resolved @emph{even\r
+on platforms without any @code{dlopen} and @code{dlsym}\r
+functions}.\r
+\r
+Consider the following alternative ways of loading code into your\r
+program, in order of increasing ``laziness'':\r
+\r
+@enumerate 1\r
+@item\r
+Linking against object files that become part of the program executable,\r
+whether or not they are referenced. If an object file cannot be found,\r
+then the linker refuses to create the executable.\r
+\r
+@item\r
+Declaring a static library to the linker, so that it is searched at link\r
+time in order to satisfy any undefined references in the above object\r
+files. If the static library cannot be found, then the linker refuses\r
+to link the executable.\r
+\r
+@item\r
+Declaring a shared library to the runtime linker, so that it is searched\r
+at runtime in order to satisfy any undefined references in the above\r
+files. If the shared library cannot be found, then the dynamic linker\r
+aborts the program before it runs.\r
+\r
+@item\r
+Dlopening a module, so that the application can resolve its own,\r
+dynamically-computed references. If there is an error opening the\r
+module, or the module is not found, then the application can recover\r
+without crashing.\r
+@end enumerate\r
+\r
+Libtool emulates @samp{-dlopen} on static platforms by linking objects\r
+into the program at compile time, and creating data structures that\r
+represent the program's symbol table.\r
+\r
+In order to use this feature, you must declare the objects you want your\r
+application to dlopen by using the @samp{-dlopen} or @samp{-dlpreopen}\r
+flags when you link your program (@pxref{Link mode}).\r
+\r
+@deftypefn {Structure} {struct} lt_dlsymlist @{ @w{const char *@var{name};} @w{lt_ptr_t @var{address};} @}\r
+The @var{name} attribute is a null-terminated character string of the\r
+symbol name, such as @code{"fprintf"}. The @var{address} attribute is a\r
+generic pointer to the appropriate object, such as @code{&fprintf}.\r
+@end deftypefn\r
+\r
+@deftypevar {const lt_dlsymlist *} lt_preloaded_symbols\r
+An array of @var{lt_symbol} structures, representing all the preloaded\r
+symbols linked into the program. For each @samp{-dlpreloaded} file \r
+there is an element with the @var{name} of the file and a @var{address} \r
+of @code{0}, followed by all symbols exported from this file.\r
+For the executable itself the special name @@PROGRAM@@ is used.\r
+The last element has a @var{name} and @var{address} of @code{0}.\r
+@end deftypevar\r
+\r
+Some compilers may allow identifiers which are not valid in ANSI C, such\r
+as dollar signs. Libtool only recognizes valid ANSI C symbols (an\r
+initial ASCII letter or underscore, followed by zero or more ASCII\r
+letters, digits, and underscores), so non-ANSI symbols will not appear\r
+in @var{lt_preloaded_symbols}.\r
+\r
+@node Finding the dlname\r
+@section Finding the correct name to dlopen\r
+@cindex names of dynamic modules\r
+@cindex dynamic modules, names\r
+\r
+After a library has been linked with @samp{-module}, it can be dlopened. \r
+Unfortunately, because of the variation in library names,\r
+your package needs to determine the correct file to dlopen.\r
+\r
+The most straightforward and flexible implementation is to determine the\r
+name at runtime, by finding the installed @samp{.la} file, and searching\r
+it for the following lines:\r
+\r
+@example\r
+# The name that we can @code{dlopen}.\r
+dlname='@var{dlname}'\r
+@end example\r
+\r
+If @var{dlname} is empty, then the library cannot be dlopened.\r
+Otherwise, it gives the dlname of the library. So, if the library was\r
+installed as @file{/usr/local/lib/libhello.la}, and the @var{dlname} was\r
+@file{libhello.so.3}, then @file{/usr/local/lib/libhello.so.3} should be\r
+dlopened.\r
+\r
+If your program uses this approach, then it should search the\r
+directories listed in the @code{LD_LIBRARY_PATH}@footnote{@code{LIBPATH}\r
+on AIX, and @code{SHLIB_PATH} on HP-UX.} environment variable, as well as\r
+the directory where libraries will eventually be installed. Searching\r
+this variable (or equivalent) will guarantee that your program can find\r
+its dlopened modules, even before installation, provided you have linked\r
+them using libtool.\r
+\r
+@node Dlopen issues\r
+@section Unresolved dlopen issues\r
+@cindex pitfalls with dlopen\r
+@cindex dlopening, pitfalls\r
+@cindex trouble with dlopen\r
+\r
+The following problems are not solved by using libtool's dlopen support:\r
+\r
+@itemize @bullet\r
+@item\r
+Dlopen functions are generally only available on shared library\r
+platforms. If you want your package to be portable to static platforms,\r
+you have to use either libltdl (@pxref{Using libltdl}) or develop your \r
+own alternatives to dlopening dynamic code.\r
+Most reasonable solutions involve writing wrapper functions for the\r
+@code{dlopen} family, which do package-specific tricks when dlopening\r
+is unsupported or not available on a given platform.\r
+\r
+@item\r
+There are major differences in implementations of the @code{dlopen}\r
+family of functions. Some platforms do not even use the same function\r
+names (notably HP-UX, with its @code{shl_load} family).\r
+\r
+@item\r
+The application developer must write a custom search function in order\r
+to discover the correct module filename to supply to @code{dlopen}.\r
+@end itemize\r
+\r
+@node Using libltdl\r
+@chapter Using libltdl\r
+@findex libltdl\r
+@findex dlopen\r
+@findex dlsym\r
+@findex dlclose\r
+@findex dlerror\r
+@findex shl_load\r
+@cindex dynamic linking, applications\r
+@cindex dlopening modules\r
+@cindex modules, dynamic\r
+@cindex application-level dynamic linking\r
+\r
+Libtool provides a small library, called @file{libltdl}, that aims at\r
+hiding the various difficulties of dlopening libraries from programmers.\r
+It consists of a header-file and a small C source file that can be\r
+distributed with applications that need dlopening functionality. On\r
+some platforms, whose dynamic linkers are too limited for a simple\r
+implementation of @file{libltdl} services, it requires GNU DLD, or it\r
+will only emulate dynamic linking with libtool's dlpreopening mechanism.\r
+\r
+@noindent\r
+libltdl supports currently the following dynamic linking mechanisms:\r
+\r
+@itemize @bullet\r
+@item\r
+@code{dlopen} (Solaris, Linux and various BSD flavors)\r
+@item\r
+@code{shl_load} (HP-UX)\r
+@item\r
+@code{LoadLibrary} (Win16 and Win32)\r
+@item\r
+@code{load_add_on} (BeOS)\r
+@item\r
+GNU DLD (emulates dynamic linking for static libraries)\r
+@item\r
+libtool's dlpreopen (see @pxref{Dlpreopening})\r
+@end itemize\r
+\r
+@noindent\r
+libltdl is licensed under the terms of the GNU Library General Public License,\r
+with the following exception:\r
+\r
+@quotation\r
+As a special exception to the GNU Library General Public License,\r
+if you distribute this file as part of a program that uses GNU libtool\r
+to create libraries and programs, you may include it under the same\r
+distribution terms that you use for the rest of that program.\r
+@end quotation\r
+\r
+@menu\r
+* Libltdl interface:: How to use libltdl in your programs.\r
+* Modules for libltdl:: Creating modules that can be @code{dlopen}ed.\r
+* Distributing libltdl:: How to distribute libltdl with your package.\r
+* Module loaders for libltdl:: Creating user defined module loaders.\r
+@end menu\r
+\r
+@node Libltdl interface\r
+@section How to use libltdl in your programs\r
+\r
+@noindent\r
+The libltdl API is similar to the dlopen interface of Solaris and Linux,\r
+which is very simple but powerful.\r
+\r
+@noindent\r
+To use libltdl in your program you have to include the header file @file{ltdl.h}:\r
+\r
+@example\r
+#include <ltdl.h>\r
+@end example\r
+\r
+@noindent\r
+Note that libltdl is not threadsafe, i.e. a multithreaded application\r
+has to use a mutex for libltdl. It was reported that GNU/Linux's glibc\r
+2.0's @code{dlopen} with @samp{RTLD_LAZY} (which libltdl uses by\r
+default) is not thread-safe, but this problem is supposed to be fixed in\r
+glibc 2.1. On the other hand, @samp{RTLD_NOW} was reported to introduce\r
+problems in multi-threaded applications on FreeBSD. Working around\r
+these problems is left as an exercise for the reader; contributions are\r
+certainly welcome.\r
+\r
+@noindent\r
+The following types are defined in @file{ltdl.h}:\r
+\r
+@deftp {Type} lt_ptr_t\r
+@code{lt_ptr_t} is a generic pointer.\r
+@end deftp\r
+\r
+@deftp {Type} lt_dlhandle\r
+@code{lt_dlhandle} is a module "handle". \r
+Every lt_dlopened module has a handle associated with it.\r
+@end deftp\r
+\r
+@deftypefn {Type} {struct} lt_dlinfo @{ @w{char *@var{filename};} @w{char *@var{name};} @w{int @var{ref_count};} @}\r
+@code{lt_dlinfo} is used to store information about a module.\r
+The @var{filename} attribute is a null-terminated character string of the\r
+real module file name. If the module is a libtool module then @var{name}\r
+is its module name (e.g. @code{"libfoo"} for @code{"dir/libfoo.la"}),\r
+otherwise it is set to @code{NULL}.\r
+The @var{ref_count} attribute is a reference counter that describes how often\r
+the same module is currently loaded.\r
+@end deftypefn\r
+\r
+@deftp {Type} lt_dlsymlist\r
+@code{lt_dlsymlist} is a symbol list for dlpreopened modules.\r
+This structure is described in @pxref{Dlpreopening}.\r
+@end deftp\r
+\r
+@page\r
+@noindent\r
+libltdl provides the following functions:\r
+\r
+@deftypefun int lt_dlinit (void)\r
+Initialize libltdl.\r
+This function must be called before using libltdl\r
+and may be called several times.\r
+Return 0 on success, otherwise the number of errors.\r
+@end deftypefun\r
+\r
+@deftypefun int lt_dlexit (void)\r
+Shut down libltdl and close all modules.\r
+This function will only then shut down libltdl when it was called as \r
+many times as @code{lt_dlinit} has been successfully called.\r
+Return 0 on success, otherwise the number of errors.\r
+@end deftypefun\r
+\r
+@deftypefun lt_dlhandle lt_dlopen (const char *@var{filename})\r
+Open the module with the file name @var{filename} and return a\r
+handle for it. @code{lt_dlopen} is able to open libtool dynamic\r
+modules, preloaded static modules, the program itself and \r
+native dynamic libraries. \r
+\r
+Unresolved symbols in the module are resolved using its dependency\r
+libraries (not implemented yet) and previously dlopened modules. If the\r
+executable using this module was linked with the @code{-export-dynamic}\r
+flag, then the global symbols in the executable will also be used to\r
+resolve references in the module.\r
+ \r
+If @var{filename} is @code{NULL} and the program was linked with\r
+@code{-export-dynamic} or @code{-dlopen self}, @code{lt_dlopen} will\r
+return a handle for the program itself, which can be used to access its\r
+symbols.\r
+\r
+If libltdl cannot find the library and the file name @var{filename} does\r
+not have a directory component it will additionally search in the\r
+following search paths for the module (in the order as follows):\r
+ \r
+@enumerate 1\r
+@item user-defined search path:\r
+This search path can be set by the program using the\r
+functions @code{lt_dlsetsearchpath} and @code{lt_dladdsearchdir}.\r
+ \r
+@item libltdl's search path:\r
+This search path is the value of the environment variable\r
+@var{LTDL_LIBRARY_PATH}.\r
+ \r
+@item system library search path:\r
+The system dependent library search path \r
+(e.g. on Linux it is @var{LD_LIBRARY_PATH}).\r
+@end enumerate\r
+\r
+Each search path must be a colon-separated list of absolute directories,\r
+for example, @code{"/usr/lib/mypkg:/lib/foo"}.\r
+ \r
+If the same module is loaded several times, the same handle is returned.\r
+If @code{lt_dlopen} fails for any reason, it returns @code{NULL}.\r
+@end deftypefun\r
+\r
+@deftypefun lt_dlhandle lt_dlopenext (const char *@var{filename})\r
+The same as @code{lt_dlopen}, except that it tries to append\r
+different file name extensions to the file name.\r
+If the file with the file name @var{filename} cannot be found\r
+libltdl tries to append the following extensions:\r
+\r
+@enumerate 1\r
+@item the libtool archive extension @samp{.la}\r
+@item the extension used for native dynamic libraries on the host platform, \r
+e.g., @samp{.so}, @samp{.sl}, etc.\r
+@end enumerate\r
+\r
+This lookup strategy was designed to allow programs that don't \r
+have knowledge about native dynamic libraries naming conventions \r
+to be able to @code{dlopen} such libraries as well as libtool modules\r
+transparently.\r
+@end deftypefun\r
+\r
+@deftypefun int lt_dlclose (lt_dlhandle @var{handle})\r
+Decrement the reference count on the module @var{handle}.\r
+If it drops to zero and no other module depends on this module,\r
+then the module is unloaded.\r
+Return 0 on success.\r
+@end deftypefun\r
+ \r
+@deftypefun lt_ptr_t lt_dlsym (lt_dlhandle @var{handle}, const char *@var{name})\r
+Return the address in the module @var{handle}, where the symbol given \r
+by the null terminated string @var{name} is loaded.\r
+If the symbol cannot be found, @code{NULL} is returned.\r
+@end deftypefun\r
+ \r
+@deftypefun {const char *} lt_dlerror (void)\r
+Return a human readable string describing the most \r
+recent error that occurred from any of libltdl's functions.\r
+Return @code{NULL} if no errors have occurred since initialization\r
+or since it was last called.\r
+@end deftypefun\r
+ \r
+@deftypefun int lt_dlpreload (const lt_dlsymlist *@var{preloaded})\r
+Register the list of preloaded modules @var{preloaded}.\r
+If @var{preloaded} is @code{NULL}, then all previously registered\r
+symbol lists, except the list set by @code{lt_dlpreload_default},\r
+are deleted. Return 0 on success.\r
+@end deftypefun\r
+\r
+@deftypefun int lt_dlpreload_default (const lt_dlsymlist *@var{preloaded})\r
+Set the default list of preloaded modules to @var{preloaded}, which\r
+won't be deleted by @code{lt_dlpreload}. Note that this function does\r
+@emph{not} require libltdl to be initialized using @code{lt_dlinit} and\r
+can be used in the program to register the default preloaded modules.\r
+Instead of calling this function directly, most programs will use the\r
+macro @code{LTDL_SET_PRELOADED_SYMBOLS}.\r
+\r
+Return 0 on success.\r
+@end deftypefun\r
+\r
+@defmac LTDL_SET_PRELOADED_SYMBOLS()\r
+Set the default list of preloaded symbols.\r
+Should be used in your program to initialize libltdl's \r
+list of preloaded modules.\r
+\r
+@example\r
+#include <ltdl.h>\r
+\r
+int main() @{\r
+ /* ... */\r
+ LTDL_SET_PRELOADED_SYMBOLS();\r
+ /* ... */\r
+@}\r
+@end example\r
+@end defmac\r
+\r
+@deftypefun int lt_dladdsearchdir (const char *@var{search_dir})\r
+Add the search directory @var{search_dir} to the user-defined library \r
+search path. Return 0 on success.\r
+@end deftypefun\r
+\r
+@deftypefun int lt_dlsetsearchpath (const char *@var{search_path})\r
+Replace the current user-defined library search path with\r
+@var{search_path}, which must be a colon-separated list of absolute\r
+directories. Return 0 on success.\r
+@end deftypefun\r
+\r
+@deftypefun {const char *} lt_dlgetsearchpath (void)\r
+Return the current user-defined library search path.\r
+@end deftypefun\r
+\r
+@deftypefun {const lt_dlinfo *} lt_dlgetinfo (lt_dlhandle @var{handle})\r
+Return a pointer to a struct that contains some information about\r
+the module @var{handle}. The contents of the struct must not be modified.\r
+Return @code{NULL} on failure. \r
+@end deftypefun\r
+\r
+@deftypefun int lt_dlforeach (int (*@var{func})(lt_dlhandle @var{handle}, lt_ptr_t @var{data}), lt_ptr_t @var{data})\r
+For each loaded module call the function @var{func}. The argument\r
+@var{handle} is the handle of one of the loaded modules, @var{data} is\r
+the @var{data} argument passed to @code{lt_dlforeach}.\r
+As soon as @var{func} returns a non-zero value for one of the handles,\r
+@code{lt_dlforeach} will stop calling @var{func} and immediately return 1.\r
+Otherwise 0 is returned.\r
+@end deftypefun\r
+\r
+@deftypevar {lt_ptr_t (*} lt_dlmalloc ) (size_t @var{size})\r
+@deftypevarx {void (*} lt_dlfree ) (lt_ptr_t @var{ptr})\r
+These variables are set to @code{malloc} and @code{free}, by default,\r
+but you can set them to any other functions that provides equivalent\r
+functionality. However, you must not modify their values after calling\r
+any libltdl function other than @code{lt_dlpreopen_default} or the macro\r
+@code{LTDL_SET_PRELOADED_SYMBOLS}.\r
+@end deftypevar\r
+\r
+@node Modules for libltdl\r
+@section Creating modules that can be @code{dlopen}ed\r
+\r
+Libtool modules are like normal libtool libraries with a few exceptions:\r
+\r
+You have to link the module with libtool's @samp{-module} switch,\r
+and you should link any program that is intended to dlopen the module with\r
+@samp{-dlopen modulename.la} so that libtool can dlpreopen the module\r
+on platforms which don't support dlopening. If the module depends on any\r
+other libraries, make sure you specify them either when you link the module\r
+or when you link programs that dlopen it.\r
+If you want to disable @pxref{Versioning} for a specific module\r
+you should link it with the @samp{-avoid-version} switch.\r
+Note that libtool modules don't need to have a "lib" prefix.\r
+However, automake 1.4 or higher is required to build such modules.\r
+\r
+Usually a set of modules provide the same interface, i.e, exports the same\r
+symbols, so that a program can dlopen them without having to know more\r
+about their internals.\r
+In order to avoid symbol conflicts all exported symbols must be prefixed\r
+with "modulename_LTX_" (@samp{modulename} is the name of the module).\r
+Internal symbols must be named in such a way that they won't conflict\r
+with other modules, for example, by prefixing them with "_modulename_".\r
+Although some platforms support having the same symbols defined more than\r
+once it is generally not portable and it makes it impossible to dlpreopen \r
+such modules. libltdl will automatically cut the prefix off to get \r
+the real name of the symbol. Additionally, it supports modules which\r
+don't use a prefix so that you can also dlopen non-libtool modules.\r
+\r
+@file{foo1.c} gives an example of a portable libtool module.\r
+Exported symbols are prefixed with "foo1_LTX_", internal symbols \r
+with "_foo1_". Aliases are defined at the beginning so that the code \r
+is more readable. \r
+\r
+@example\r
+/* aliases for the exported symbols */\r
+#define foo foo1_LTX_foo\r
+#define bar foo1_LTX_bar\r
+\r
+/* a global variable definition */\r
+int bar = 1;\r
+\r
+/* a private function */\r
+int _foo1_helper() @{\r
+ return bar;\r
+@}\r
+\r
+/* an exported function */\r
+int foo() @{\r
+ return _foo_helper();\r
+@}\r
+@end example\r
+\r
+@noindent\r
+The @file{Makefile.am} contains the necessary rules to build the \r
+module @file{foo1.la}:\r
+\r
+@example\r
+...\r
+lib_LTLIBRARIES = foo1.la\r
+\r
+foo1_la_SOURCES = foo1.c\r
+foo1_la_LDFLAGS = -module\r
+...\r
+@end example\r
+\r
+@node Distributing libltdl\r
+@section How to distribute libltdl with your package\r
+\r
+Even though libltdl is installed together with libtool, you may wish to\r
+include libltdl in the distribution of your package, for the convenience \r
+of users of your package that don't have libtool or libltdl installed.\r
+In this case, you must decide whether to manually add the @code{ltdl}\r
+objects to your package, or else which flavor of libltdl you want to use:\r
+a convenience library or an installable libtool library.\r
+\r
+The most simplistic way to add @code{ltdl} to your package is to copy\r
+the source files, @file{ltdl.c} and @file{ltdl.h}, to a source directory\r
+withing your package and to build and link them along with the rest of\r
+your sources. To help you do this, the m4 macros for autoconf are\r
+available in @file{ltdl.m4}. You must ensure that they are available in\r
+@file{aclocal.m4} before you run autoconf -- by appending the contents\r
+of @file{ltdl.m4} to @file{acinclude.m4}, if you are using automake, or\r
+to @file{aclocal.m4} if you are not. Having made the macros available,\r
+you must add a call to the @samp{AC_LIB_LTDL} macro to your package's\r
+@file{configure.in} to perform the configure time checks required to\r
+build @file{ltdl.o} correctly. This method has problems if you then try\r
+to link the package binaries with an installed libltdl, or a library\r
+which depends on libltdl: you may have problems with duplicate symbol\r
+definitions.\r
+\r
+One advantage of the convenience library is that it is not installed, so\r
+the fact that you use libltdl will not be apparent to the user, and it\r
+will not overwrite a pre-installed version of libltdl a user might have.\r
+On the other hand, if you want to upgrade libltdl for any reason \r
+(e.g. a bugfix) you'll have to recompile your package instead of just \r
+replacing an installed version of libltdl.\r
+However, if your programs or libraries are linked with other libraries\r
+that use such a pre-installed version of libltdl, you may get linker\r
+errors or run-time crashes. Another problem is that you cannot link the\r
+convenience library into more than one libtool library, then link a\r
+single program with these libraries, because you may get duplicate\r
+symbols. In general you can safely use the convenience library in programs\r
+which don't depend on other libraries that might use libltdl too.\r
+In order to enable this flavor of libltdl, you should add the\r
+line @samp{AC_LIBLTDL_CONVENIENCE} to your @file{configure.in},\r
+@emph{before} @samp{AM_PROG_LIBTOOL}.\r
+\r
+In order to select the installable version of libltdl, you should add a\r
+call of the macro @samp{AC_LIBLTDL_INSTALLABLE} to your\r
+@file{configure.in} @emph{before} @samp{AM_PROG_LIBTOOL}. This macro\r
+will check whether libltdl is already installed and, if not, request the\r
+libltdl embedded in your package to be built and installed. Note,\r
+however, that no version checking is performed. The user may override\r
+the test and determine that the libltdl embedded must be installed,\r
+regardless of the existence of another version, using the configure\r
+switch @samp{--enable-ltdl-install}.\r
+\r
+In order to embed libltdl into your package, just add @samp{--ltdl} to\r
+the @code{libtoolize} command line. It will copy the libltdl sources\r
+to a subdirectory @samp{libltdl} in your package.\r
+Both macros accept an optional argument to specify the location\r
+of the @samp{libltdl} directory. By the default both macros assume that it\r
+is @samp{$@{top_builddir@}/libltdl}.\r
+\r
+Whatever macro you use, it is up to you to ensure that your\r
+@file{configure.in} will configure libltdl, using\r
+@samp{AC_CONFIG_SUBDIRS}, and that your @file{Makefile}s will start\r
+sub-makes within libltdl's directory, using automake's @var{SUBDIRS},\r
+for example. Both macros define the shell variables @var{LIBLTDL}, to\r
+the link flag that you should use to link with libltdl, and\r
+@var{INCLTDL}, to the preprocessor flag that you should use to compile\r
+with programs that include @file{ltdl.h}. It is up to you to use\r
+@samp{AC_SUBST} to ensure that this variable will be available in\r
+@file{Makefile}s, or add them to variables that are @samp{AC_SUBST}ed by\r
+default, such as @var{LIBS} and @var{CPPFLAGS}.\r
+\r
+If you're using the convenience libltdl, @var{LIBLTDL} will be the\r
+pathname for the convenience version of libltdl and @var{INCLTDL} will be\r
+@samp{-I} followed by the directory that contains libltdl, both starting\r
+with @samp{$@{top_builddir@}/}.\r
+\r
+If you request an installed version of libltdl and one is\r
+found@footnote{Even if libltdl is installed,\r
+@samp{AC_LIBLTDL_INSTALLABLE} may fail to detect it, if libltdl depends\r
+on symbols provided by libraries other than the C library. In this\r
+case, it will needlessly build and install libltdl.}, @var{LIBLTDL} will\r
+be set to @samp{-lltdl} and @var{INCLTDL} will be empty (which is just a\r
+blind assumption that @file{ltdl.h} is somewhere in the include path if\r
+libltdl is in the library path). If an installable version of libltdl\r
+must be built, its pathname, starting with @samp{$@{top_builddir@}/},\r
+will be stored in @var{LIBLTDL}, and @var{INCLTDL} will be set just like\r
+in the case of convenience library.\r
+\r
+So, when you want to link a program with libltdl, be it a convenience,\r
+installed or installable library, just compile with @samp{$(INCLTDL)}\r
+and link it with @samp{$(LIBLTDL)}, using libtool.\r
+\r
+You should probably also add @samp{AC_LIBTOOL_DLOPEN} to your\r
+@file{configure.in} @emph{before} @samp{AM_PROG_LIBTOOL}, otherwise\r
+libtool will assume no dlopening mechanism is supported, and revert to\r
+dlpreopening, which is probably not what you want.\r
+\r
+Avoid using the @code{-static} or @code{-all-static} switches when\r
+linking programs with libltdl. This will not work on all platforms,\r
+because the dlopening functions may not be available for static linking.\r
+\r
+The following example shows you how to embed the convenience libltdl in\r
+your package. In order to use the installable variant just replace\r
+@samp{AC_LIBLTDL_CONVENIENCE} with @samp{AC_LIBLTDL_INSTALLABLE}. We\r
+assume that libltdl was embedded using @samp{libtoolize --ltdl}.\r
+\r
+configure.in:\r
+@example\r
+...\r
+dnl Enable building of the convenience library\r
+dnl and set LIBLTDL accordingly\r
+AC_LIBLTDL_CONVENIENCE\r
+dnl Substitute INCLTDL and LIBLTDL in the Makefiles\r
+AC_SUBST(INCLTDL)\r
+AC_SUBST(LIBLTDL)\r
+dnl Check for dlopen support\r
+AC_LIBTOOL_DLOPEN\r
+dnl Configure libtool\r
+AM_PROG_LIBTOOL\r
+dnl Configure libltdl\r
+AC_CONFIG_SUBDIRS(libltdl)\r
+...\r
+@end example\r
+\r
+Makefile.am:\r
+@example\r
+...\r
+SUBDIRS = libltdl\r
+\r
+INCLUDES = $(INCLTDL)\r
+\r
+myprog_LDFLAGS = -export-dynamic\r
+# The quotes around -dlopen below fool automake into accepting it\r
+myprog_LDADD = $(LIBLTDL) "-dlopen" self "-dlopen" libfoo.la\r
+myprog_DEPENDENCIES = $(LIBLTDL) libfoo.la\r
+...\r
+@end example\r
+\r
+\r
+@node Module loaders for libltdl\r
+@section How to create and register new module loaders\r
+\r
+Sometimes libltdl's many ways of gaining access to modules are not\r
+sufficient for the purposes of a project. You can write your own\r
+loader, and register it with libltdl so that @code{lt_dlopen} will be\r
+able to use it. \r
+\r
+Writing a loader involves writing at least three functions which can be\r
+called by @code{lt_dlopen}, @code{lt_dlsym} and @code{lt_dlclose}.\r
+Optionally, you can provide a finalisation function to perform any\r
+cleanup operations when @code{lt_dlexit} executes, and a symbol prefix\r
+string which will be prepended to any symbols passed to @code{lt_dlsym}.\r
+These functions must match the function pointer types below, after\r
+which they can be allocated to an instance of @code{lt_user_dlloader}\r
+and registered.\r
+\r
+Registering the loader requires that you choose a name for it, so that it\r
+can be recognised by @code{lt_find_dlloader} and removed with\r
+@code{lt_remove_dlloader}. The name you choose must be unique, and not\r
+already in use by libltdl's builtin loaders:\r
+\r
+@table @asis\r
+@item "dlopen"\r
+The system dynamic library loader, if one exists.\r
+@item "dld"\r
+The @sc{gnu} dld loader, if @file{libdld} wasinstalled when libltdl was\r
+built.\r
+@item "dlpreload"\r
+The loader for @code{lt_dlopen}ing of preloaded static modules.\r
+@end table\r
+\r
+The prefix "dl" is reserved for loaders supplied with future versions of \r
+libltdl, so you should not use that for your own loader names.\r
+\r
+@noindent\r
+The following types are defined in @file{ltdl.h}:\r
+\r
+@deftp {Type} lt_module_t\r
+@code{lt_module_t} is a dlloader dependent module.\r
+The dynamic module loader extensions communicate using these low\r
+level types.\r
+@end deftp\r
+\r
+@deftp {Type} lt_dlloader_t\r
+@code{lt_dlloader_t} is a handle for module loader types.\r
+@end deftp\r
+\r
+@deftypefn {Type} {struct} lt_user_dlloader @{@w{const char *@var{sym_prefix};} @w{lt_module_open_t *@var{module_open};} @w{lt_module_close_t *@var{module_close};} @w{lt_find_sym_t *@var{find_sym};} @w{lt_dlloader_exit_t *@var{dlloader_exit};} @}\r
+If you want to define a new way to open dynamic modules, and have the\r
+@code{lt_dlopen} @sc{api} use it, you need to instantiate one of these\r
+structures and pass it to @code{lt_add_dlloader}.\r
+@end deftypefn\r
+\r
+@deftypefn {Type} lt_module_t lt_module_open_t (@w{const char *@var{filename}})\r
+The type of the loader function for an @code{lt_dlloader_t} module\r
+loader. Implementation of such a function should attempt to load the\r
+named module, and return an @code{lt_module_t} suitable for passing in\r
+to the associated @code{lt_module_close_t} and @code{lt_sym_find_t}\r
+function pointers. If the function fails it should return NULL, and set \r
+the error message with @code{lt_dlseterror}.\r
+@end deftypefn\r
+\r
+@deftypefn {Type} int lt_module_close_t (@w{lt_module_t @var{module}})\r
+The type of the unloader function for a user defined module loader.\r
+Implementatation of such a function should attempt to release \r
+any resources tied up by the @var{module} module, and then unload it\r
+from memory. If the function fails for some reason, set the error\r
+message with @code{lt_dlseterror} and return non-zero.\r
+@end deftypefn\r
+\r
+@deftypefn {Type} lt_ptr_t lt_find_sym_t (@w{lt_module_t @var{module},} @w{const char *@var{symbol}}) \r
+The type of the symbol lookup function for a user defined module loader.\r
+Implementation of such a function should return the address of the named\r
+@var{symbol} in the module @var{module}, or else set the error message\r
+with @code{lt_dlseterror} and return NULL if lookup fails.\r
+@end deftypefn\r
+\r
+@deftypefn {Type} int lt_dlloader_exit_t (void)\r
+The type of the finalisation function for a user defined module loader.\r
+Implementation of such a function should free any resources associated\r
+with the loader. If non-NULL, the function will be called by\r
+@code{lt_dlexit}.\r
+@end deftypefn\r
+\r
+For example:\r
+\r
+@example\r
+int\r
+register_myloader (void)\r
+@{\r
+ lt_user_dlloader dlloader;\r
+\r
+ /* User modules are responsible for their own initialisation. */\r
+ if (myloader_init () != 0)\r
+ return MYLOADER_INIT_ERROR;\r
+\r
+ dlloader.sym_prefix = NULL;\r
+ dlloader.module_open = myloader_open;\r
+ dlloader.module_close = myloader_close;\r
+ dlloader.find_sym = myloader_find_sym.\r
+ dlloader.dlloader_exit = myloader_exit;\r
+\r
+ /* Add my loader as the default module loader. */\r
+ if (lt_add_dlloader (lt_next_dlloader (NULL), &dlloader, "myloader") != 0)\r
+ return ERROR;\r
+\r
+ return OK;\r
+@}\r
+@end example\r
+\r
+Note that if there is any initialisation required for the loader,\r
+it must be performed manually before the loader is registered --\r
+libltdl doesn't handle user loader initialisation.\r
+\r
+Finalisation @emph{is} handled by libltdl however, and it is important\r
+to ensure the @code{dlloader_exit} callback releases any resources claimed\r
+during the initialisation phase.\r
+\r
+@page\r
+@noindent\r
+libltdl provides the following functions for writing your own module\r
+loaders:\r
+\r
+@deftypefun int lt_add_dlloader (@w{lt_dlloader_t *@var{place},} @w{lt_user_dlloader *@var{dlloader},} @w{const char *@var{loader_name}})\r
+Add a new module loader to the list of all loaders, either as the\r
+last loader (if @var{place} is @code{NULL}), else immediately before the\r
+loader passed as @var{place}. @var{loader_name} will be returned by\r
+@code{lt_dlloader_name} if it is subsequently passed a newly\r
+registered loader. These @var{loader_name}s must be unique, or\r
+@code{lt_remove_dlloader} and @code{lt_find_dlloader} cannot\r
+work. Returns 0 for success.\r
+\r
+@example\r
+@{\r
+ /* Make myloader be the last one. */\r
+ if (lt_add_dlloader (NULL, myloader) != 0)\r
+ perror (lt_dlerror ());\r
+@}\r
+@end example\r
+@end deftypefun\r
+\r
+@deftypefun int lt_remove_dlloader (@w{const char *@var{loader_name}})\r
+Remove the loader identified by the unique name, @var{loader_name}.\r
+Before this can succeed, all modules opened by the named loader must\r
+have been closed. Returns 0 for success, otherwise an error message can \r
+be obtained from @code{lt_dlerror}.\r
+\r
+@example\r
+@{\r
+ /* Remove myloader. */\r
+ if (lt_remove_dlloader ("myloader") != 0)\r
+ perror (lt_dlerror ());\r
+@}\r
+@end example\r
+@end deftypefun\r
+\r
+@deftypefun lt_dlloader_t *lt_next_dlloader (@w{lt_dlloader_t *@var{place}})\r
+Iterate over the module loaders, returning the first loader if @var{place} is\r
+@code{NULL}, and the next one on subsequent calls. The handle is for use with\r
+@code{lt_add_dlloader}.\r
+\r
+@example\r
+@{\r
+ /* Make myloader be the first one. */\r
+ if (lt_add_dlloader (lt_next_dlloader (NULL), myloader) != 0)\r
+ return ERROR;\r
+@}\r
+@end example\r
+@end deftypefun\r
+\r
+@deftypefun lt_dlloader_t *lt_find_dlloader (@w{const char *@var{loader_name}})\r
+Return the first loader with a matching @var{loader_name} identifier, or else\r
+@code{NULL}, if the identifier is not found.\r
+\r
+The identifiers which may be used by ltdl itself, if the host\r
+architecture supports them are @dfn{dlopen}@footnote{This is used for\r
+the host dependent module loading @sc{api} -- @code{shl_load} and\r
+@code{LoadLibrary} for example}, @dfn{dld} and @dfn{dlpreload}.\r
+\r
+@example\r
+@{\r
+ /* Add a user loader as the next module loader to be tried if\r
+ the standard dlopen loader were to fail when lt_dlopening. */\r
+ if (lt_add_dlloader (lt_find_dlloader ("dlopen"), myloader) != 0)\r
+ return ERROR;\r
+@}\r
+@end example\r
+@end deftypefun\r
+\r
+@deftypefun char *lt_dlloader_name (@w{lt_dlloader_t *@var{place}})\r
+Return the identifying name of @var{PLACE}, as obtained from\r
+@code{lt_next_dlloader} or @code{lt_find_dlloader}. If this function fails,\r
+it will return @code{NULL} and set an error for retrieval with\r
+@code{lt_dlerror}.\r
+@end deftypefun\r
+\r
+@subsection Error handling within user module loaders\r
+\r
+@deftypefun int lt_dladderror (@w{const char *@var{diagnostic}})\r
+This function allows you to integrate your own error messages into\r
+@code{lt_dlerror}. Pass in a suitable diagnostic message for return by\r
+@code{lt_dlerror}, and an error identifier for use with\r
+@code{lt_dlseterror} is returned.\r
+\r
+If the allocation of an identifier fails, this function returns -1.\r
+\r
+@example\r
+int myerror = lt_dladderror ("Doh!");\r
+if (myerror < 0)\r
+ perror (lt_dlerror ());\r
+@end example\r
+@end deftypefun\r
+\r
+@deftypefun int lt_dlseterror (@w{int @var{errorcode}})\r
+When writing your own module loaders, you should use this function to\r
+raise errors so that they are propogated through the @code{lt_dlerror}\r
+interface. All of the standard errors used by libltdl are declared in\r
+@file{ltdl.h}, or you can add more of your own with\r
+@code{lt_dladderror}. This function returns 0 on success.\r
+\r
+@example\r
+if (lt_dlseterror (LTDL_ERROR_NO_MEMORY) != 0)\r
+ perror (lt_dlerror ());\r
+@end example\r
+@end deftypefun\r
+\r
+@node Other languages\r
+@chapter Using libtool with other languages\r
+@cindex C, not using\r
+@cindex languages, non-C\r
+@cindex C++, using\r
+\r
+Libtool was first implemented in order to add support for writing shared\r
+libraries in the C language. However, over time, libtool is being\r
+integrated with other languages, so that programmers are free to reap\r
+the benefits of shared libraries in their favorite programming language.\r
+\r
+This chapter describes how libtool interacts with other languages,\r
+and what special considerations you need to make if you do not use C.\r
+\r
+@menu\r
+* Configuration tags::\r
+* C++ libraries::\r
+@end menu\r
+\r
+@node Configuration tags\r
+@section Configuration tags\r
+@cindex Configuration tags\r
+@cindex tags\r
+\r
+A single libtool script may support multiple configurations. By\r
+default, it will only support C compilation, but additional\r
+configuration tags can be created, using @samp{ltconfig --add-tag}, so\r
+that libtool can support other compilers. Such configuration tags can\r
+be used to select native compilers instead of cross ones, or compilers\r
+of other languages.\r
+\r
+For example, in order to create a tag for a C++ compiler @samp{CC}, you\r
+could run:\r
+\r
+@example\r
+$ @kbd{LTCC=gcc CC=c++ CFLAGS=-g CPPFLAGS=-Dfoo \}\r
+> @kbd{./ltconfig -o libtool --add-tag=CXX ltcf-cxx.sh}\r
+@end example\r
+\r
+@samp{ltcf-cxx.sh} is a shell script fragment that configures C++\r
+specific variables that get placed within the appended configuration\r
+tag. Another shell script called @samp{ltcf-c.sh} that contains C\r
+compiler configurations also exists but it should not be used by the\r
+user. It is used internally by the ltconfig script.\r
+\r
+Note that you should set @var{LTCC} to a valid C compiler, because\r
+libtool may need to compile additional C sources internally. Note also\r
+that, although @samp{CC} is not a C compiler, you should use variables\r
+such as @var{CC}, @var{CFLAGS} and @var{CPPFLAGS} to tell libtool which\r
+flags to use when compiling test programs.\r
+\r
+You can use existing compiler/language specific shell script fragments,\r
+such as @samp{ltcf-cxx.sh}, as a reference for other compilers/languages\r
+you would like libtool to support.\r
+\r
+A potential problem may occur if you use variables when setting\r
+@var{LTCC} and @var{CC}. For example, a problem will occur if you do\r
+the following:\r
+\r
+@example\r
+$ @kbd{LTCC=$CC CC=$CXX ./ltconfig -o libtool --add-tag=CXX ltcf-cxx.sh}\r
+@end example\r
+\r
+In this example, @var{CC} is set to the C++ compiler and LTCC is set to\r
+the compiler pointed to by @var{$CC}. However, @var{CC} was previously\r
+set to the C++ compiler @var{$CXX}, which causes LTCC to be set to the\r
+C++ compiler @var{$CXX}, too. This is a problem because LTCC must be a\r
+valid C compiler, not a C++ compiler for example.\r
+\r
+If @samp{ltconfig} is unable to determine the host type then you must\r
+explicitly provide a host when invoking @samp{ltconfig}. This is\r
+typically necessary for new very platforms and many cross-compiled\r
+platforms. For example, assuming that your host is @samp{i386-nto} then\r
+@samp{ltconfig} could be invoked as follows:\r
+\r
+@example\r
+$ @kbd{LTCC=$CC CC=$CXX ./ltconfig -o libtool \}\r
+> @kbd{--add-tag=CXX ltcf-cxx.sh i386-nto}\r
+@end example\r
+\r
+After a configuration tag has been added using the @samp{--add-tag}\r
+option, whenever you want to compile or link a library using\r
+@samp{c++}, you should run:\r
+\r
+@example\r
+$ @kbd{./libtool --mode=compile c++ -c test.cc}\r
+@end example\r
+\r
+Libtool will automatically detect the appropriate tagged configuration\r
+to use by matching the compiler used in the above command with the one\r
+the tagged configuration was configured with.\r
+\r
+The tagged configuration that libtool uses can be explicitly specified\r
+by using the @samp{--tag} option as follows:\r
+\r
+@example\r
+$ @kbd{./libtool --tag=CXX --mode=compile c++ -c test.cc}\r
+@end example\r
+\r
+Conceptually, tags are cumulative, i.e., they could only set a couple of\r
+configuration variables, leaving others untouched. In practice, any tag\r
+created with ltconfig will override all libtool configuration variables.\r
+Only the two pre-defined tags, @samp{disable-shared} and\r
+@samp{disable-static}, override a single variable, and can be used\r
+cumulatively, after other tags.\r
+\r
+@emph{NOTE}: C++ support may be automatically added to your package by\r
+adding the @code{AC_LIBTOOL_CXX} macro to your package\r
+@file{configure.in} file.\r
+\r
+@node C++ libraries\r
+@section Writing libraries for C++\r
+@c FIXME: in the TOC, the ++ is too large (seems to be math mode)\r
+@cindex trouble with C++\r
+@cindex pitfalls using C++\r
+@cindex C++, pitfalls\r
+\r
+@emph{NOTE}: The problems described in this section may no longer\r
+relevant due to the @samp{libtool} multi-language support. To enable\r
+C++ support in libtool, use the @code{AC_LIBTOOL_CXX} macro in your\r
+@file{configure.in} file.\r
+\r
+Creating libraries of C++ code should be a fairly straightforward\r
+process, because its object files differ from C ones in only three ways:\r
+\r
+@enumerate 1\r
+@item\r
+Because of name mangling, C++ libraries are only usable by the C++\r
+compiler that created them. This decision was made by the designers of\r
+C++ in order to protect users from conflicting implementations of\r
+features such as constructors, exception handling, and RTTI.\r
+\r
+@item\r
+On some systems, the C++ compiler must take special actions for the\r
+dynamic linker to run dynamic (i.e., run-time) initializers. This means\r
+that we should not call @file{ld} directly to link such libraries, and\r
+we should use the C++ compiler instead.\r
+\r
+@item\r
+C++ compilers will link some Standard C++ library in by default, but\r
+libtool does not know which are these libraries, so it cannot even run\r
+the inter-library dependence analyzer to check how to link it in.\r
+Therefore, running @file{ld} to link a C++ program or library is deemed\r
+to fail. However, running the C++ compiler directly may lead to\r
+problems related with inter-library dependencies.\r
+@end enumerate\r
+\r
+The conclusion is that libtool is not ready for general use for C++\r
+libraries. You should avoid any global or static variable\r
+initializations that would cause an ``initializer element is not\r
+constant'' error if you compiled them with a standard C compiler.\r
+\r
+There are other ways of working around this problem, but they are beyond\r
+the scope of this manual.\r
+\r
+Furthermore, you'd better find out, at configure time, what are the C++\r
+Standard libraries that the C++ compiler will link in by default, and\r
+explicitly list them in the link command line. Hopefully, in the\r
+future, libtool will be able to do this job by itself.\r
+\r
+\r
+@node Troubleshooting\r
+@chapter Troubleshooting\r
+@cindex troubleshooting\r
+@cindex problems, solving\r
+@cindex solving problems\r
+@cindex problems, blaming somebody else for\r
+\r
+Libtool is under constant development, changing to remain up-to-date\r
+with modern operating systems. If libtool doesn't work the way you\r
+think it should on your platform, you should read this chapter to help\r
+determine what the problem is, and how to resolve it.\r
+\r
+@menu\r
+* Libtool test suite:: Libtool's self-tests.\r
+* Reporting bugs:: How to report problems with libtool.\r
+@end menu\r
+\r
+@node Libtool test suite\r
+@section The libtool test suite\r
+@cindex test suite\r
+\r
+Libtool comes with its own set of programs that test its capabilities,\r
+and report obvious bugs in the libtool program. These tests, too, are\r
+constantly evolving, based on past problems with libtool, and known\r
+deficiencies in other operating systems.\r
+\r
+As described in the @file{INSTALL} file, you may run @kbd{make check}\r
+after you have built libtool (possibly before you install it) in order\r
+to make sure that it meets basic functional requirements.\r
+\r
+@menu\r
+* Test descriptions:: The contents of the test suite.\r
+* When tests fail:: What to do when a test fails.\r
+@end menu\r
+\r
+@node Test descriptions\r
+@subsection Description of test suite\r
+\r
+Here is a list of the current programs in the test suite, and what they\r
+test for:\r
+\r
+@table @file\r
+\r
+@item cdemo-conf.test\r
+@itemx cdemo-exec.test\r
+@itemx cdemo-make.test\r
+@itemx cdemo-static.test\r
+@itemx cdemo-shared.test\r
+@pindex cdemo-conf.test\r
+@pindex cdemo-exec.test\r
+@pindex cdemo-make.test\r
+@pindex cdemo-static.test\r
+@pindex cdemo-shared.test\r
+These programs check to see that the @file{cdemo} subdirectory of the\r
+libtool distribution can be configured and built correctly.\r
+\r
+The @file{cdemo} subdirectory contains a demonstration of libtool\r
+convenience libraries, a mechanism that allows build-time static\r
+libraries to be created, in a way that their components can be later\r
+linked into programs or other libraries, even shared ones.\r
+\r
+The tests @file{cdemo-make.test} and @file{cdemo-exec.test} are executed\r
+three times, under three different libtool configurations:\r
+@file{cdemo-conf.test} configures @file{cdemo/libtool} to build both\r
+static and shared libraries (the default for platforms that support\r
+both), @file{cdemo-static.test} builds only static libraries\r
+(@samp{--disable-shared}), and @file{cdemo-shared.test} builds only\r
+shared libraries (@samp{--disable-static}).\r
+\r
+@item demo-conf.test\r
+@itemx demo-exec.test\r
+@itemx demo-inst.test\r
+@itemx demo-make.test\r
+@itemx demo-unst.test\r
+@itemx demo-static.test\r
+@itemx demo-shared.test\r
+@itemx demo-nofast.test\r
+@itemx demo-pic.test\r
+@itemx demo-nopic.test\r
+@pindex demo-conf.test\r
+@pindex demo-exec.test\r
+@pindex demo-inst.test\r
+@pindex demo-make.test\r
+@pindex demo-unst.test\r
+@pindex demo-static.test\r
+@pindex demo-shared.test\r
+@pindex demo-nofast.test\r
+@pindex demo-pic.test\r
+@pindex demo-nopic.test\r
+These programs check to see that the @file{demo} subdirectory of the\r
+libtool distribution can be configured, built, installed, and\r
+uninstalled correctly.\r
+\r
+The @file{demo} subdirectory contains a demonstration of a trivial\r
+package that uses libtool. The tests @file{demo-make.test},\r
+@file{demo-exec.test}, @file{demo-inst.test} and\r
+@file{demo-unst.test} are executed four times, under four different\r
+libtool configurations: @file{demo-conf.test} configures\r
+@file{demo/libtool} to build both static and shared libraries,\r
+@file{demo-static.test} builds only static libraries\r
+(@samp{--disable-shared}), and @file{demo-shared.test} builds only\r
+shared libraries (@samp{--disable-static}).\r
+@file{demo-nofast.test} configures @file{demo/libtool} to\r
+disable the fast-install mode (@samp{--enable-fast-install=no}).\r
+@file{demo-pic.test} configures @file{demo/libtool} to\r
+prefer building PIC code (@samp{--with-pic}), @file{demo-nopic.test}\r
+to prefer non-PIC code (@samp{--without-pic}).\r
+\r
+@item deplibs.test\r
+@pindex deplibs.test\r
+Many systems cannot link static libraries into shared libraries.\r
+libtool uses a @code{deplibs_check_method} to prevent such cases.\r
+This tests checks whether libtool's @code{deplibs_check_method}\r
+works properly.\r
+\r
+@item hardcode.test\r
+@pindex hardcode.test\r
+On all systems with shared libraries, the location of the library can be\r
+encoded in executables that are linked against it @pxref{Linking\r
+executables}. This test checks the conditions under which your system\r
+linker hardcodes the library location, and guarantees that they\r
+correspond to libtool's own notion of how your linker behaves.\r
+\r
+@item build-relink.test\r
+@pindex build-relink.test\r
+Checks whether variable @var{shlibpath_overrides_runpath} is properly\r
+set. If the test fails and @var{VERBOSE} is set, it will indicate what\r
+the variable should have been set to.\r
+\r
+@item noinst-link.test\r
+@pindex noinst-link.test\r
+Checks whether libtool will not try to link with a previously installed\r
+version of a library when it should be linking with a just-built one.\r
+\r
+@item depdemo-conf.test\r
+@itemx depdemo-exec.test\r
+@itemx depdemo-inst.test\r
+@itemx depdemo-make.test\r
+@itemx depdemo-unst.test\r
+@itemx depdemo-static.test\r
+@itemx depdemo-shared.test\r
+@itemx depdemo-nofast.test\r
+@pindex depdemo-conf.test\r
+@pindex depdemo-exec.test\r
+@pindex depdemo-inst.test\r
+@pindex depdemo-make.test\r
+@pindex depdemo-unst.test\r
+@pindex depdemo-static.test\r
+@pindex depdemo-shared.test\r
+@pindex depdemo-nofast.test\r
+These programs check to see that the @file{depdemo} subdirectory of the\r
+libtool distribution can be configured, built, installed, and\r
+uninstalled correctly.\r
+\r
+The @file{depdemo} subdirectory contains a demonstration of inter-library\r
+dependencies with libtool. The test programs link some interdependent\r
+libraries.\r
+\r
+The tests @file{depdemo-make.test}, @file{depdemo-exec.test},\r
+@file{depdemo-inst.test} and @file{depdemo-unst.test} are executed\r
+four times, under four different libtool configurations:\r
+@file{depdemo-conf.test} configures @file{depdemo/libtool} to build both\r
+static and shared libraries, @file{depdemo-static.test} builds only static\r
+libraries (@samp{--disable-shared}), and @file{depdemo-shared.test} builds\r
+only shared libraries (@samp{--disable-static}).\r
+@file{depdemo-nofast.test} configures @file{depdemo/libtool} to\r
+disable the fast-install mode (@samp{--enable-fast-install=no}.\r
+\r
+@item mdemo-conf.test\r
+@itemx mdemo-exec.test\r
+@itemx mdemo-inst.test\r
+@itemx mdemo-make.test\r
+@itemx mdemo-unst.test\r
+@itemx mdemo-static.test\r
+@itemx mdemo-shared.test\r
+@pindex mdemo-conf.test\r
+@pindex mdemo-exec.test\r
+@pindex mdemo-inst.test\r
+@pindex mdemo-make.test\r
+@pindex mdemo-unst.test\r
+@pindex mdemo-static.test\r
+@pindex mdemo-shared.test\r
+These programs check to see that the @file{mdemo} subdirectory of the\r
+libtool distribution can be configured, built, installed, and\r
+uninstalled correctly.\r
+\r
+The @file{mdemo} subdirectory contains a demonstration of a package that\r
+uses libtool and the system independent dlopen wrapper @file{libltdl} to\r
+load modules. The library @file{libltdl} provides a dlopen wrapper for\r
+various platforms (Linux, Solaris, HP/UX etc.) including support for\r
+dlpreopened modules (@pxref{Dlpreopening}).\r
+\r
+The tests @file{mdemo-make.test}, @file{mdemo-exec.test},\r
+@file{mdemo-inst.test} and @file{mdemo-unst.test} are executed\r
+three times, under three different libtool configurations:\r
+@file{mdemo-conf.test} configures @file{mdemo/libtool} to build both\r
+static and shared libraries, @file{mdemo-static.test} builds only static\r
+libraries (@samp{--disable-shared}), and @file{mdemo-shared.test} builds\r
+only shared libraries (@samp{--disable-static}).\r
+\r
+@item tagdemo-conf.test\r
+@itemx tagdemo-exec.test\r
+@itemx tagdemo-make.test\r
+@itemx tagdemo-static.test\r
+@itemx tagdemo-shared.test\r
+@pindex tagdemo-conf.test\r
+@pindex tagdemo-exec.test\r
+@pindex tagdemo-make.test\r
+@pindex tagdemo-static.test\r
+@pindex tagdemo-shared.test\r
+These programs check to see that the @file{tagdemo} subdirectory of the\r
+libtool distribution can be configured and built correctly.\r
+\r
+The @file{tagdemo} subdirectory contains a demonstration of a package\r
+that uses libtool and its tagged configuration support\r
+(@pxref{Configuration tags}) build a C++ library. C++ shared library\r
+support is enabled by using the @code{AC_LIBTOOL_CXX} macro in\r
+@file{tagdemo/configure.in}.\r
+\r
+The tests @file{tagdemo-make.test}, and @file{tagdemo-exec.test}, are\r
+executed three times, under three different libtool configurations:\r
+@file{tagdemo-conf.test} configures @file{tagdemo/libtool} to build both\r
+static and shared libraries, @file{tagdemo-static.test} builds only\r
+static libraries (@samp{--disable-shared}), and\r
+@file{tagdemo-shared.test} builds only shared libraries\r
+(@samp{--disable-static}).\r
+\r
+@item dryrun.test\r
+@pindex dryrun.test\r
+This test checks whether libtool's @code{--dry-run} mode works properly.\r
+\r
+@item assign.test\r
+@pindex assign.test\r
+Checks whether we don't put break or continue on the same \r
+line as an assignment in the libtool script.\r
+\r
+@item link.test\r
+@pindex link.test\r
+This test guarantees that linking directly against a non-libtool static\r
+library works properly.\r
+\r
+@item link-2.test\r
+@pindex link-2.test\r
+This test makes sure that files ending in @samp{.lo} are never linked\r
+directly into a program file.\r
+\r
+@item nomode.test\r
+@pindex nomode.test\r
+Check whether we can actually get help for libtool.\r
+\r
+@item quote.test\r
+@pindex quote.test\r
+This program checks libtool's metacharacter quoting.\r
+\r
+@item sh.test\r
+@pindex sh.test\r
+Checks whether a `test' command was forgotten in libtool.\r
+\r
+@item suffix.test\r
+@pindex suffix.test\r
+When other programming languages are used with libtool (@pxref{Other\r
+languages}), the source files may end in suffixes other than @samp{.c}.\r
+This test validates that libtool can handle suffixes for all the file\r
+types that it supports, and that it fails when the suffix is invalid.\r
+\r
+@end table\r
+\r
+@node When tests fail\r
+@subsection When tests fail\r
+@cindex failed tests\r
+@cindex tests, failed\r
+\r
+Each of the above tests are designed to produce no output when they are\r
+run via @kbd{make check}. The exit status of each program tells the\r
+@file{Makefile} whether or not the test succeeded.\r
+\r
+If a test fails, it means that there is either a programming error in\r
+libtool, or in the test program itself.\r
+\r
+To investigate a particular test, you may run it directly, as you would\r
+a normal program. When the test is invoked in this way, it produces\r
+output which may be useful in determining what the problem is.\r
+\r
+Another way to have the test programs produce output is to set the\r
+@var{VERBOSE} environment variable to @samp{yes} before running them.\r
+For example, @kbd{env VERBOSE=yes make check} runs all the tests, and\r
+has each of them display debugging information.\r
+\r
+@node Reporting bugs\r
+@section Reporting bugs\r
+@cindex bug reports\r
+@cindex reporting bugs\r
+@cindex problem reports\r
+\r
+If you think you have discovered a bug in libtool, you should think\r
+twice: the libtool maintainer is notorious for passing the buck (or\r
+maybe that should be ``passing the bug''). Libtool was invented to fix\r
+known deficiencies in shared library implementations, so, in a way, most\r
+of the bugs in libtool are actually bugs in other operating systems.\r
+However, the libtool maintainer would definitely be happy to add support\r
+for somebody else's buggy operating system. [I wish there was a good\r
+way to do winking smiley-faces in Texinfo.]\r
+\r
+Genuine bugs in libtool include problems with shell script portability,\r
+documentation errors, and failures in the test suite (@pxref{Libtool\r
+test suite}).\r
+\r
+First, check the documentation and help screens to make sure that the\r
+behaviour you think is a problem is not already mentioned as a feature.\r
+\r
+Then, you should read the Emacs guide to reporting bugs (@pxref{Bugs, ,\r
+Reporting Bugs, emacs, The Emacs Manual}). Some of the details\r
+listed there are specific to Emacs, but the principle behind them is a\r
+general one.\r
+\r
+Finally, send a bug report to @value{BUGADDR} with any appropriate\r
+@emph{facts}, such as test suite output (@pxref{When tests fail}), all\r
+the details needed to reproduce the bug, and a brief description of why\r
+you think the behaviour is a bug. Be sure to include the word\r
+``libtool'' in the subject line, as well as the version number you are\r
+using (which can be found by typing @kbd{ltconfig --version}).\r
+\r
+@node Maintaining\r
+@chapter Maintenance notes for libtool\r
+\r
+This chapter contains information that the libtool maintainer finds\r
+important. It will be of no use to you unless you are considering\r
+porting libtool to new systems, or writing your own libtool.\r
+\r
+@menu\r
+* New ports:: How to port libtool to new systems.\r
+* Tested platforms:: When libtool was last tested.\r
+* Platform quirks:: Information about different library systems.\r
+* libtool script contents:: Configuration information that libtool uses.\r
+* Cheap tricks:: Making libtool maintainership easier.\r
+@end menu\r
+\r
+@node New ports\r
+@section Porting libtool to new systems\r
+\r
+Before you embark on porting libtool to an unsupported system, it is\r
+worthwhile to send e-mail to @value{MAILLIST}, to make sure that you are\r
+not duplicating existing work.\r
+\r
+If you find that any porting documentation is missing, please complain! \r
+Complaints with patches and improvements to the documentation, or to\r
+libtool itself, are more than welcome.\r
+\r
+@menu\r
+* Information sources:: Where to find relevant documentation\r
+* Porting inter-library dependencies:: Implementation details explained\r
+@end menu\r
+\r
+@node Information sources\r
+@subsection Information sources\r
+\r
+Once it is clear that a new port is necessary, you'll generally need the\r
+following information:\r
+\r
+@table @asis\r
+@item canonical system name\r
+You need the output of @code{config.guess} for this system, so that you\r
+can make changes to the libtool configuration process without affecting\r
+other systems.\r
+\r
+@item man pages for @code{ld} and @code{cc}\r
+These generally describe what flags are used to generate PIC, to create\r
+shared libraries, and to link against only static libraries. You may\r
+need to follow some cross references to find the information that is\r
+required.\r
+\r
+@item man pages for @code{ld.so}, @code{rtld}, or equivalent\r
+These are a valuable resource for understanding how shared libraries are\r
+loaded on the system.\r
+\r
+@item man page for @code{ldconfig}, or equivalent\r
+This page usually describes how to install shared libraries.\r
+\r
+@item output from @kbd{ls -l /lib /usr/lib}\r
+This shows the naming convention for shared libraries on the system,\r
+including which names should be symbolic links.\r
+\r
+@item any additional documentation\r
+Some systems have special documentation on how to build and install\r
+shared libraries.\r
+@end table\r
+\r
+If you know how to program the Bourne shell, then you can complete the\r
+port yourself; otherwise, you'll have to find somebody with the relevant\r
+skills who will do the work. People on the libtool mailing list are\r
+usually willing to volunteer to help you with new ports, so you can send\r
+the information to them.\r
+\r
+To do the port yourself, you'll definitely need to modify the\r
+@code{ltconfig} script in order to make platform-specific changes to the\r
+configuration process. You should search the script for the\r
+@code{PORTME} keyword, which will give you some hints on what you'll\r
+need to change. In general, all that is involved is modifying the\r
+appropriate configuration variables (@pxref{libtool script contents}).\r
+\r
+Your best bet is to find an already-supported system that is similar to\r
+yours, and make your changes based on that. In some cases, however,\r
+your system will differ significantly from every other supported system,\r
+and it may be necessary to add new configuration variables, and modify\r
+the @code{ltmain.sh} script accordingly. Be sure to write to the\r
+mailing list before you make changes to @code{ltmain.sh}, since they may\r
+have advice on the most effective way of accomplishing what you want.\r
+\r
+@node Porting inter-library dependencies\r
+@subsection Porting inter-library dependencies support\r
+@cindex inter-library dependency\r
+@vindex deplibs_check_method\r
+\r
+Since version 1.2c, libtool has re-introduced the ability to do\r
+inter-library dependency on some platforms, thanks to a patch by Toshio\r
+Kuratomi @email{badger@@prtr-13.ucsc.edu}. Here's a shortened version\r
+of the message that contained his patch:\r
+\r
+The basic architecture is this: in @file{ltconfig.in}, the person who\r
+writes libtool makes sure @samp{$deplibs} is included in\r
+@samp{$archive_cmds} somewhere and also sets the variable\r
+@samp{$deplibs_check_method}, and maybe @samp{$file_magic_cmd} when\r
+@samp{deplibs_check_method} is file_magic.\r
+\r
+@samp{deplibs_check_method} can be one of five things:\r
+@table @samp\r
+@item file_magic [@var{regex}]\r
+@vindex file_magic\r
+@vindex file_magic_cmd\r
+@vindex file_magic_test_file\r
+looks in the library link path for libraries that have the right\r
+libname. Then it runs @samp{$file_magic_cmd} on the library and checks\r
+for a match against @samp{regex} using @code{egrep}. When\r
+@var{file_magic_test_file} is set in @file{ltconfig}, it is used as an\r
+argument to @samp{$file_magic_cmd} in order to verify whether the\r
+regular expression matches its output, and warn the user otherwise.\r
+\r
+@item test_compile \r
+@vindex test_compile\r
+just checks whether it is possible to link a program out of a list of\r
+libraries, and checks which of those are listed in the output of\r
+@code{ldd}. It is currently unused, and will probably be dropped in the\r
+future.\r
+\r
+@item pass_all\r
+@vindex pass_all\r
+will pass everything without any checking. This may work on platforms\r
+in which code is position-independent by default and inter-library\r
+dependencies are properly supported by the dynamic linker, for example,\r
+on DEC OSF/1 3 and 4.\r
+\r
+@item none\r
+@vindex none\r
+It causes deplibs to be reassigned deplibs="". That way\r
+@samp{archive_cmds} can contain deplibs on all platforms, but not have\r
+deplibs used unless needed.\r
+\r
+@item unknown\r
+@vindex unknown\r
+is the default for all systems unless overridden in @file{ltconfig.in}.\r
+It is the same as @samp{none}, but it documents that we really don't\r
+know what the correct value should be, and we welcome patches that\r
+improve it.\r
+@end table\r
+\r
+Then in @file{ltmain.in} we have the real workhorse: a little\r
+initialization and postprocessing (to setup/release variables for use\r
+with eval echo libname_spec etc.) and a case statement that decides\r
+which method is being used. This is the real code... I wish I could\r
+condense it a little more, but I don't think I can without function\r
+calls. I've mostly optimized it (moved things out of loops, etc) but\r
+there is probably some fat left. I thought I should stop while I was\r
+ahead, work on whatever bugs you discover, etc before thinking about\r
+more than obvious optimizations.\r
+\r
+@node Tested platforms\r
+@section Tested platforms\r
+\r
+This table describes when libtool was last known to be tested on\r
+platforms where it claims to support shared libraries:\r
+\r
+@example\r
+@include PLATFORMS\r
+@end example\r
+\r
+Note: The vendor-distributed HP-UX @code{sed}(1) programs are horribly\r
+broken, and cannot handle libtool's requirements, so users may report\r
+unusual problems. There is no workaround except to install a working\r
+@code{sed} (such as GNU @code{sed}) on these systems.\r
+\r
+Note: The vendor-distributed NCR MP-RAS @code{cc} programs emits\r
+copyright on standard error that confuse tests on size of\r
+@file{conftest.err}. The workaround is to specify @code{CC}\r
+when run @code{configure} with @kbd{CC='cc -Hnocopyr'}.\r
+\r
+@node Platform quirks\r
+@section Platform quirks\r
+\r
+This section is dedicated to the sanity of the libtool maintainers. It\r
+describes the programs that libtool uses, how they vary from system to\r
+system, and how to test for them.\r
+\r
+Because libtool is a shell script, it can be difficult to understand\r
+just by reading it from top to bottom. This section helps show why\r
+libtool does things a certain way. Combined with the scripts\r
+themselves, you should have a better sense of how to improve libtool, or\r
+write your own.\r
+\r
+@menu\r
+* References:: Finding more information.\r
+* Compilers:: Creating object files from source files.\r
+* Reloadable objects:: Binding object files together.\r
+* Archivers:: Programs that create static archives.\r
+@end menu\r
+\r
+@node References\r
+@subsection References\r
+\r
+The following is a list of valuable documentation references:\r
+\r
+@itemize @bullet\r
+@item\r
+SGI's IRIX Manual Pages, which can be found at\r
+@url{http://techpubs.sgi.com/cgi-bin/infosrch.cgi?cmd=browse&db=man}.\r
+\r
+@item\r
+Sun's free service area\r
+(@url{http://www.sun.com/service/online/free.html}) and documentation\r
+server (@url{http://docs.sun.com/}).\r
+\r
+@item \r
+Compaq's Tru64 UNIX online documentation is at \r
+(@url{http://tru64unix.compaq.com/faqs/publications/pub_page/doc_list.html})\r
+with C++ documentation at \r
+(@url{http://tru64unix.compaq.com/cplus/docs/index.htm}). \r
+\r
+@item \r
+Hewlett-Packard has online documentation at \r
+(@url{http://docs.hp.com/index.html}). \r
+\r
+@item \r
+IBM has online documentation at \r
+(@url{http://www.rs6000.ibm.com/resource/aix_resource/Pubs/}). \r
+@end itemize\r
+\r
+@node Compilers\r
+@subsection Compilers\r
+\r
+The only compiler characteristics that affect libtool are the flags\r
+needed (if any) to generate PIC objects. In general, if a C compiler\r
+supports certain PIC flags, then any derivative compilers support the\r
+same flags. Until there are some noteworthy exceptions to this rule,\r
+this section will document only C compilers.\r
+\r
+The following C compilers have standard command line options, regardless\r
+of the platform:\r
+\r
+@table @code\r
+@item gcc\r
+\r
+This is the GNU C compiler, which is also the system compiler for many\r
+free operating systems (FreeBSD, GNU/Hurd, GNU/Linux, Lites, NetBSD, and\r
+OpenBSD, to name a few).\r
+\r
+The @samp{-fpic} or @samp{-fPIC} flags can be used to generate\r
+position-independent code. @samp{-fPIC} is guaranteed to generate\r
+working code, but the code is slower on m68k, m88k, and Sparc chips.\r
+However, using @samp{-fpic} on those chips imposes arbitrary size limits\r
+on the shared libraries.\r
+@end table\r
+\r
+The rest of this subsection lists compilers by the operating system that\r
+they are bundled with:\r
+\r
+@c FIXME these should all be better-documented\r
+\r
+@table @code\r
+@item aix3*\r
+@itemx aix4*\r
+AIX compilers have no PIC flags, since AIX has been ported only to\r
+PowerPC and RS/6000 chips. @footnote{All code compiled for the PowerPC\r
+and RS/6000 chips (@code{powerpc-*-*}, @code{powerpcle-*-*}, and\r
+@code{rs6000-*-*}) is position-independent, regardless of the operating\r
+system or compiler suite. So, ``regular objects'' can be used to build\r
+shared libraries on these systems and no special PIC compiler flags are\r
+required.}\r
+\r
+@item hpux10*\r
+Use @samp{+Z} to generate PIC.\r
+\r
+@item osf3*\r
+Digital/UNIX 3.x does not have PIC flags, at least not on the PowerPC\r
+platform.\r
+\r
+@item solaris2*\r
+Use @samp{-KPIC} to generate PIC.\r
+\r
+@item sunos4*\r
+Use @samp{-PIC} to generate PIC.\r
+@end table\r
+\r
+@node Reloadable objects\r
+@subsection Reloadable objects\r
+\r
+On all known systems, a reloadable object can be created by running\r
+@kbd{ld -r -o @var{output}.o @var{input1}.o @var{input2}.o}. This\r
+reloadable object may be treated as exactly equivalent to other\r
+objects.\r
+\r
+@node Archivers\r
+@subsection Archivers\r
+\r
+On all known systems, building a static library can be accomplished by\r
+running @kbd{ar cru lib@var{name}.a @var{obj1}.o @var{obj2}.o @dots{}},\r
+where the @samp{.a} file is the output library, and each @samp{.o} file is an\r
+object file.\r
+\r
+On all known systems, if there is a program named @code{ranlib}, then it\r
+must be used to ``bless'' the created library before linking against it,\r
+with the @kbd{ranlib lib@var{name}.a} command. Some systems, like Irix,\r
+use the @code{ar ts} command, instead.\r
+\r
+@node libtool script contents\r
+@section @code{libtool} script contents\r
+@cindex implementation of libtool\r
+@cindex libtool implementation\r
+\r
+The @code{libtool} script is generated by @code{ltconfig}\r
+(@pxref{Configuring}). From libtool version 0.7 to 1.0, this script\r
+simply set shell variables, then sourced the libtool backend,\r
+@code{ltmain.sh}. @code{ltconfig} from libtool version 1.1 and later\r
+inlines the contents of @code{ltmain.sh} into the generated\r
+@code{libtool}, which improves performance on many systems.\r
+\r
+The convention used for naming variables which hold shell commands for\r
+delayed evaluation, is to use the suffix @code{_cmd} where a single\r
+line of valid shell script is needed, and the suffix @code{_cmds} where\r
+multiple lines of shell script @strong{may} be delayed for later\r
+evaluation. By convention, @code{_cmds} variables delimit the\r
+evaluation units with the @code{~} character where necessary.\r
+\r
+Here is a listing of each of the configuration variables, and how they\r
+are used within @code{ltmain.sh}:\r
+\r
+@defvar AR\r
+The name of the system library archiver.\r
+@end defvar\r
+\r
+@defvar CC\r
+The name of the C compiler used to configure libtool.\r
+@end defvar\r
+\r
+@defvar LD\r
+The name of the linker that libtool should use internally for reloadable\r
+linking and possibly shared libraries.\r
+@end defvar\r
+\r
+@defvar LTCONFIG_VERSION\r
+This is set to the version number of the @code{ltconfig} script, to\r
+prevent mismatches between the configuration information in\r
+@code{libtool}, and how that information is used in @code{ltmain.sh}.\r
+@end defvar\r
+\r
+@defvar NM\r
+The name of a BSD-compatible @code{nm} program, which produces listings\r
+of global symbols in one the following formats:\r
+\r
+@example\r
+@var{address} C @var{global-variable-name}\r
+@var{address} D @var{global-variable-name}\r
+@var{address} T @var{global-function-name}\r
+@end example\r
+@end defvar\r
+\r
+@defvar RANLIB\r
+Set to the name of the ranlib program, if any.\r
+@end defvar\r
+\r
+@defvar allow_undefined_flag\r
+The flag that is used by @samp{archive_cmds} in order to declare that\r
+there will be unresolved symbols in the resulting shared library.\r
+Empty, if no such flag is required. Set to @samp{unsupported} if there\r
+is no way to generate a shared library with references to symbols that\r
+aren't defined in that library.\r
+@end defvar\r
+\r
+@defvar always_export_symbols\r
+Whether libtool should automatically generate a list of exported symbols\r
+using @var{export_symbols_cmds} before linking an archive.\r
+Set to @samp{yes} or @samp{no}. Default is @samp{no}.\r
+@end defvar\r
+\r
+@defvar archive_cmds\r
+@defvarx archive_expsym_cmds\r
+@defvarx old_archive_cmds\r
+Commands used to create shared libraries, shared libraries with\r
+@samp{-export-symbols} and static libraries, respectively.\r
+@end defvar\r
+\r
+@defvar old_archive_from_new_cmds\r
+If the shared library depends on a static library,\r
+@samp{old_archive_from_new_cmds} contains the commands used to create that\r
+static library. If this variable is not empty, @samp{old_archive_cmds} is\r
+not used.\r
+@end defvar\r
+\r
+@defvar old_archive_from_expsyms_cmds\r
+If a static library must be created from the export symbol list in order to\r
+correctly link with a shared library, @samp{old_archive_from_expsyms_cmds}\r
+contains the commands needed to create that static library. When these\r
+commands are executed, the variable @var{soname} contains the name of the\r
+shared library in question, and the @var{$objdir/$newlib} contains the\r
+path of the static library these commands should build. After executing\r
+these commands, libtool will proceed to link against @var{$objdir/$newlib}\r
+instead of @var{soname}.\r
+@end defvar\r
+\r
+@defvar build_libtool_libs\r
+Whether libtool should build shared libraries on this system. Set to\r
+@samp{yes} or @samp{no}.\r
+@end defvar\r
+\r
+@defvar build_old_libs\r
+Whether libtool should build static libraries on this system. Set to\r
+@samp{yes} or @samp{no}.\r
+@end defvar\r
+\r
+@defvar compiler_c_o\r
+Whether the compiler supports the @code{-c} and @code{-o} options \r
+simultaneously. Set to @samp{yes} or @samp{no}.\r
+@end defvar\r
+\r
+@defvar compiler_o_lo\r
+Whether the compiler supports compiling directly to a ".lo" file, \r
+i.e whether object files do not have to have the suffix ".o".\r
+Set to @samp{yes} or @samp{no}.\r
+@end defvar\r
+\r
+@defvar dlopen_support\r
+Whether @code{dlopen} is supported on the platform.\r
+Set to @samp{yes} or @samp{no}.\r
+@end defvar\r
+\r
+@defvar dlopen_self\r
+Whether it is possible to @code{dlopen} the executable itself.\r
+Set to @samp{yes} or @samp{no}.\r
+@end defvar\r
+\r
+@defvar dlopen_self_static\r
+Whether it is possible to @code{dlopen} the executable itself, when it\r
+is linked statically (@samp{-all-static}). Set to @samp{yes} or\r
+@samp{no}.\r
+@end defvar\r
+\r
+@defvar echo\r
+An @code{echo} program which does not interpret backslashes as an\r
+escape character.\r
+@end defvar\r
+\r
+@defvar exclude_expsyms\r
+List of symbols that should not be listed in the preloaded symbols.\r
+@end defvar\r
+\r
+@defvar export_dynamic_flag_spec\r
+Compiler link flag that allows a dlopened shared library to reference\r
+symbols that are defined in the program.\r
+@end defvar\r
+\r
+@defvar export_symbols_cmds\r
+Commands to extract exported symbols from @var{libobjs} to the\r
+file @var{export_symbols}.\r
+@end defvar\r
+\r
+@defvar extract_expsyms_cmds\r
+Commands to extract the exported symbols list from a shared library.\r
+These commands are executed if there is no file @var{$objdir/$soname-def},\r
+and should write the names of the exported symbols to that file, for\r
+the use of @samp{old_archive_from_expsyms_cmds}.\r
+@end defvar\r
+\r
+@defvar fast_install\r
+Determines whether libtool will privilege the installer or the\r
+developer. The assumption is that installers will seldom run programs\r
+in the build tree, and the developer will seldom install. This is only\r
+meaningful on platforms in which @var{shlibpath_overrides_runpath} is\r
+not @samp{yes}, so @var{fast_install} will be set to @samp{needless} in\r
+this case. If @var{fast_install} set to @samp{yes}, libtool will create\r
+programs that search for installed libraries, and, if a program is run\r
+in the build tree, a new copy will be linked on-demand to use the\r
+yet-to-be-installed libraries. If set to @samp{no}, libtool will create\r
+programs that use the yet-to-be-installed libraries, and will link\r
+a new copy of the program at install time. The default value is\r
+@samp{yes} or @samp{needless}, depending on platform and configuration\r
+flags, and it can be turned from @samp{yes} to @samp{no} with the\r
+configure flag @samp{--disable-fast-install}.\r
+@end defvar\r
+\r
+@defvar finish_cmds\r
+Commands to tell the dynamic linker how to find shared libraries in a\r
+specific directory.\r
+@end defvar\r
+\r
+@defvar finish_eval\r
+Same as @var{finish_cmds}, except the commands are not displayed.\r
+@end defvar\r
+\r
+@defvar fix_srcfile_path\r
+Expression to fix the shell variable $srcfile for the compiler.\r
+@end defvar\r
+\r
+@defvar global_symbol_pipe\r
+A pipeline that takes the output of @var{NM}, and produces a listing of\r
+raw symbols followed by their C names. For example:\r
+\r
+@example\r
+$ @kbd{eval "$NM progname | $global_symbol_pipe"}\r
+D @var{symbol1} @var{C-symbol1}\r
+T @var{symbol2} @var{C-symbol2}\r
+C @var{symbol3} @var{C-symbol3}\r
+@dots{}\r
+$\r
+@end example\r
+\r
+The first column contains the symbol type (used to tell data from code\r
+on some platforms), but its meaning is system dependent.\r
+@end defvar\r
+\r
+@defvar global_symbol_to_cdecl\r
+A pipeline that translates the output of @var{global_symbol_pipe} into\r
+proper C declarations. On platforms whose linkers differentiate code\r
+from data, such as HP/UX, data symbols will be declared as such, and\r
+code symbols will be declared as functions. On platforms that don't\r
+care, everything is assumed to be data.\r
+@end defvar\r
+\r
+@defvar hardcode_action\r
+Either @samp{immediate} or @samp{relink}, depending on whether shared\r
+library paths can be hardcoded into executables before they are installed,\r
+or if they need to be relinked.\r
+@end defvar\r
+\r
+@defvar hardcode_direct\r
+Set to @samp{yes} or @samp{no}, depending on whether the linker\r
+hardcodes directories if a library is directly specified on the command\r
+line (such as @samp{@var{dir}/lib@var{name}.a}) when\r
+@var{hardcode_libdir_flag_spec} is specified.\r
+@end defvar\r
+\r
+@defvar hardcode_into_libs\r
+Whether the platform supports hardcoding of run-paths into libraries.\r
+If enabled, linking of programs will be much simpler but libraries will\r
+need to be relinked during installation. Set to @samp{yes} or @samp{no}.\r
+@end defvar\r
+\r
+@defvar hardcode_libdir_flag_spec\r
+Flag to hardcode a @var{libdir} variable into a binary, so that the\r
+dynamic linker searches @var{libdir} for shared libraries at runtime.\r
+If it is empty, libtool will try to use some other hardcoding mechanism.\r
+@end defvar\r
+\r
+@defvar hardcode_libdir_separator\r
+If the compiler only accepts a single @var{hardcode_libdir_flag}, then\r
+this variable contains the string that should separate multiple\r
+arguments to that flag.\r
+@end defvar\r
+\r
+@defvar hardcode_minus_L\r
+Set to @samp{yes} or @samp{no}, depending on whether the linker\r
+hardcodes directories specified by @samp{-L} flags into the resulting\r
+executable when @var{hardcode_libdir_flag_spec} is specified.\r
+@end defvar\r
+\r
+@defvar hardcode_shlibpath_var\r
+Set to @samp{yes} or @samp{no}, depending on whether the linker\r
+hardcodes directories by writing the contents of @samp{$shlibpath_var}\r
+into the resulting executable when @var{hardcode_libdir_flag_spec} is\r
+specified. Set to @samp{unsupported} if directories specified by\r
+@samp{$shlibpath_var} are searched at run time, but not at link time.\r
+@end defvar\r
+\r
+@defvar host\r
+@defvarx host_alias\r
+For information purposes, set to the specified and canonical names of\r
+the system that libtool was configured for.\r
+@end defvar\r
+\r
+@defvar include_expsyms\r
+List of symbols that must always be exported when using @var{export_symbols}.\r
+@end defvar\r
+\r
+@defvar libext\r
+The standard old archive suffix (normally "a").\r
+@end defvar\r
+\r
+@defvar libname_spec\r
+The format of a library name prefix. On all Unix systems, static\r
+libraries are called @samp{lib@var{name}.a}, but on some systems (such\r
+as OS/2 or MS-DOS), the library is just called @samp{@var{name}.a}.\r
+@end defvar\r
+\r
+@defvar library_names_spec\r
+A list of shared library names. The first is the name of the file,\r
+the rest are symbolic links to the file. The name in the list is\r
+the file name that the linker finds when given @samp{-l@var{name}}.\r
+@end defvar\r
+\r
+@defvar link_all_deplibs\r
+Whether libtool must link a program against all its dependency libraries.\r
+Set to @samp{yes} or @samp{no}. Default is @samp{unknown}, which is\r
+a synonym for @samp{yes}.\r
+@end defvar\r
+\r
+@defvar link_static_flag\r
+Linker flag (passed through the C compiler) used to prevent dynamic\r
+linking.\r
+@end defvar\r
+\r
+@defvar need_lib_prefix\r
+Whether libtool should automatically prefix module names with 'lib'.\r
+Set to @samp{yes} or @samp{no}. By default, it is @samp{unknown}, which \r
+means the same as @samp{yes}, but documents that we are not really sure\r
+about it.\r
+@samp{yes} means that it is possible both to @code{dlopen} and to\r
+link against a library without 'lib' prefix,\r
+i.e. it requires @var{hardcode_direct} to be @samp{yes}.\r
+@end defvar\r
+\r
+@defvar need_version\r
+Whether versioning is required for libraries, i.e. whether the\r
+dynamic linker requires a version suffix for all libraries.\r
+Set to @samp{yes} or @samp{no}. By default, it is @samp{unknown}, which \r
+means the same as @samp{yes}, but documents that we are not really sure\r
+about it.\r
+@end defvar\r
+\r
+@defvar need_locks\r
+Whether files must be locked to prevent conflicts when compiling \r
+simultaneously. Set to @samp{yes} or @samp{no}.\r
+@end defvar\r
+\r
+@defvar no_builtin_flag\r
+Compiler flag to disable builtin functions that conflict with declaring\r
+external global symbols as @code{char}.\r
+@end defvar\r
+\r
+@defvar no_undefined_flag\r
+The flag that is used by @samp{archive_cmds} in order to declare that\r
+there will be no unresolved symbols in the resulting shared library.\r
+Empty, if no such flag is required.\r
+@end defvar\r
+\r
+@defvar objdir\r
+The name of the directory that contains temporary libtool files.\r
+@end defvar\r
+\r
+@defvar objext\r
+The standard object file suffix (normally "o").\r
+@end defvar\r
+\r
+@defvar pic_flag\r
+Any additional compiler flags for building library object files.\r
+@end defvar\r
+\r
+@defvar postinstall_cmds\r
+@defvarx old_postinstall_cmds\r
+Commands run after installing a shared or static library, respectively.\r
+@end defvar\r
+\r
+@defvar postuninstall_cmds\r
+@defvarx old_postuninstall_cmds\r
+Commands run after uninstalling a shared or static library, respectively.\r
+@end defvar\r
+\r
+@defvar reload_cmds\r
+@defvarx reload_flag\r
+Commands to create a reloadable object.\r
+@end defvar\r
+\r
+@defvar runpath_var\r
+The environment variable that tells the linker which directories to\r
+hardcode in the resulting executable.\r
+@end defvar\r
+\r
+@defvar shlibpath_overrides_runpath\r
+Indicates whether it is possible to override the hard-coded library\r
+search path of a program with an environment variable. If this is set\r
+to no, libtool may have to create two copies of a program in the build\r
+tree, one to be installed and one to be run in the build tree only.\r
+When each of these copies is created depends on the value of\r
+@code{fast_install}. The default value is @samp{unknown}, which is\r
+equivalent to @samp{no}.\r
+@end defvar\r
+\r
+@defvar shlibpath_var\r
+The environment variable that tells the dynamic linker where to find\r
+shared libraries.\r
+@end defvar\r
+\r
+@defvar soname_spec\r
+The name coded into shared libraries, if different from the real name of\r
+the file.\r
+@end defvar\r
+\r
+@defvar striplib\r
+@defvarx old_striplib\r
+Command to strip a shared (@code{striplib}) or static (@code{old_striplib})\r
+library, respectively. If these variables are empty, the strip flag\r
+in the install mode will be ignored for libraries (@pxref{Install mode}).\r
+@end defvar\r
+\r
+@defvar sys_lib_dlsearch_path_spec\r
+Expression to get the run-time system library search path. Directories\r
+that appear in this list are never hard-coded into executables.\r
+@end defvar\r
+\r
+@defvar sys_lib_search_path_spec\r
+Expression to get the compile-time system library search path. This\r
+variable is used by libtool when it has to test whether a certain\r
+library is shared or static. The directories listed in\r
+@var{shlibpath_var} are automatically appended to this list, every time\r
+libtool runs (i.e., not at configuration time), because some linkers use\r
+this variable to extend the library search path. Linker switches such\r
+as @code{-L} also augment the search path.\r
+@end defvar\r
+\r
+@defvar thread_safe_flag_spec\r
+Linker flag (passed through the C compiler) used to generate thread-safe\r
+libraries.\r
+@end defvar\r
+\r
+@defvar version_type\r
+The library version numbering type. One of @samp{libtool},\r
+@samp{linux}, @samp{osf}, @samp{sunos}, or @samp{none}.\r
+@end defvar\r
+\r
+@defvar whole_archive_flag_spec\r
+Compiler flag to generate shared objects from convenience archives.\r
+@end defvar\r
+\r
+@defvar wl\r
+The C compiler flag that allows libtool to pass a flag directly to the\r
+linker. Used as: @code{$@{wl@}@var{some-flag}}.\r
+@end defvar\r
+\r
+Variables ending in @samp{_cmds} or @samp{_eval} contain a\r
+semicolon-separated list of commands that are @code{eval}ed one after\r
+another. If any of the commands return a nonzero exit status, libtool\r
+generally exits with an error message.\r
+\r
+Variables ending in @samp{_spec} are @code{eval}ed before being used by\r
+libtool.\r
+\r
+@node Cheap tricks\r
+@section Cheap tricks\r
+\r
+Here are a few tricks that you can use in order to make maintainership\r
+easier:\r
+\r
+@itemize @bullet\r
+@item\r
+When people report bugs, ask them to use the @samp{--config},\r
+@samp{--debug}, or @samp{--features} flags, if you think they will help\r
+you. These flags are there to help you get information directly, rather\r
+than having to trust second-hand observation.\r
+\r
+@item\r
+Rather than reconfiguring libtool every time I make a change to\r
+@code{ltconfig.in} or @code{ltmain.in}, I keep a permanent\r
+@code{libtool} script in my @var{PATH}, which sources @code{ltmain.in}\r
+directly.\r
+\r
+The following steps describe how to create such a script, where\r
+@code{/home/src/libtool} is the directory containing the libtool source\r
+tree, @code{/home/src/libtool/libtool} is a libtool script that has been\r
+configured for your platform, and @code{~/bin} is a directory in your\r
+@var{PATH}:\r
+\r
+@example\r
+trick$ @kbd{cd ~/bin}\r
+trick$ @kbd{sed '/^# ltmain\.sh/q' /home/src/libtool/libtool > libtool}\r
+trick$ @kbd{cat >> libtool\r
+LTCONFIG_VERSION="@@VERSION@@"\r
+. /home/src/libtool/ltmain.in\r
+^D}\r
+trick$ @kbd{chmod +x libtool}\r
+trick$ @kbd{libtool --version}\r
+ltmain.sh (GNU @@PACKAGE@@) @@VERSION@@\r
+trick$\r
+@end example\r
+@end itemize\r
+\r
+The output of the final @samp{libtool --version} command shows that the\r
+@code{ltmain.in} script is being used directly. Now, modify\r
+@code{~/bin/libtool} or @code{/home/src/libtool/ltmain.in} directly in\r
+order to test new changes without having to rerun @code{ltconfig}.\r
+\r
+@page\r
+@node Index\r
+@unnumbered Index\r
+\r
+@printindex cp\r
+\r
+@c summarycontents\r
+@contents\r
+@bye\r
projects / thirdparty / libtool.git / commitdiff
