-\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\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
+\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.
+
+When GNU automake is used, you should use @code{noinst_LTLIBRARIES}
+instead of @code{lib_LTLIBRARIES} for convenience libraries, so that
+the @samp{-rpath} option is not passed when they are linked.
+
+As a rule of thumb, link a libtool convenience library into at most one
+libtool library, and never into a program, and link libtool static
+convenience libraries only into programs, and only if you need to carry
+library dependency information to the user of the static convenience
+library.
+
+@cindex standalone binaries
+Another common situation where static linking is desirable is in
+creating a standalone binary. Use libtool to do the linking and add the
+@samp{-all-static} flag.
+
+@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/}).
+
+@item
+Compaq's Tru64 UNIX online documentation is at
+(@url{http://tru64unix.compaq.com/faqs/publications/pub_page/doc_list.html})
+with C++ documentation at
+(@url{http://tru64unix.compaq.com/cplus/docs/index.htm}).
+
+@item
+Hewlett-Packard has online documentation at
+(@url{http://docs.hp.com/index.html}).
+
+@item
+IBM has online documentation at
+(@url{http://www.rs6000.ibm.com/resource/aix_resource/Pubs/}).
+@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
projects / thirdparty / libtool.git / commitdiff
