From: Robert Boehne Date: Fri, 27 Oct 2000 20:01:43 +0000 (+0000) Subject: * docs/libtool.texi: Added pointers to documentation X-Git-Tag: multi-language-merge-point~126 X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=b5bde1b843ba04698ce6c2c94ddd13a355440128;p=thirdparty%2Flibtool.git * docs/libtool.texi: Added pointers to documentation of Hewlett-Packard, Compaq Tru64 and IBM AIX systems. --- diff --git a/ChangeLog b/ChangeLog index 97683d4de..7e4fd5441 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,8 @@ +2000-10-27 Robert Boehne + + * docs/libtool.texi: Added pointers to documentation + of Hewlett-Packard, Compaq Tru64 and IBM AIX systems. + 2000-10-10 Alexandre Oliva * libtool.m4 (AC_LIBTOOL_CXX, AC_LIBTOOL_GCJ): Pass LD down to diff --git a/doc/libtool.texi b/doc/libtool.texi index 027f35fc2..eef5bbeb5 100644 --- a/doc/libtool.texi +++ b/doc/libtool.texi @@ -1,4741 +1,4755 @@ -\input texinfo @c -*-texinfo-*- - -@c $Id$ - -@c %**start of header -@setfilename libtool.info -@settitle Libtool -@c For double-sided printing, uncomment: -@c @setchapternewpage odd -@c %**end of header - -@include version.texi -@set BUGADDR the libtool bug reporting address @email{bug-libtool@@gnu.org} -@set MAILLIST the libtool mailing list @email{libtool@@gnu.org} -@set objdir .libs - -@dircategory GNU programming tools -@direntry -* Libtool: (libtool). Generic shared library support script. -@end direntry - -@dircategory Individual utilities -@direntry -* libtoolize: (libtool)Invoking libtoolize. Adding libtool support. -@end direntry - -@ifinfo -This file documents GNU Libtool @value{VERSION} - -Copyright (C) 1996-2000 Free Software Foundation, Inc. - -Permission is granted to make and distribute verbatim copies of this -manual provided the copyright notice and this permission notice are -preserved on all copies. - -@ignore -Permission is granted to process this file through TeX and print the -results, provided the printed document carries copying permission notice -identical to this one except for the removal of this paragraph - - -@end ignore -Permission is granted to copy and distribute modified versions of this -manual under the conditions for verbatim copying, provided that the -entire resulting derived work is distributed under the terms of a -permission notice identical to this one. - -Permission is granted to copy and distribute translations of this manual -into another language, under the above conditions for modified versions, -except that this permission notice may be stated in a translation -approved by the Foundation. -@end ifinfo - - -@titlepage -@title GNU Libtool -@subtitle For version @value{VERSION}, @value{UPDATED} -@author Gordon Matzigkeit -@author Alexandre Oliva -@author Thomas Tanner -@author Gary V. Vaughan - -@page -@vskip 0pt plus 1filll -Copyright @copyright{} 1996-2000 Free Software Foundation, Inc. - -Permission is granted to make and distribute verbatim copies of this -manual provided the copyright notice and this permission notice are -preserved on all copies. - -Permission is granted to copy and distribute modified versions of this -manual under the conditions for verbatim copying, provided that the -entire resulting derived work is distributed under the terms of a -permission notice identical to this one. - -Permission is granted to copy and distribute translations of this manual -into another language, under the above conditions for modified versions, -except that this permission notice may be stated in a translation -approved by the Free Software Foundation. -@end titlepage - -@c Put everything in one index (arbitrarily chosen to be the concept index). -@syncodeindex vr cp -@syncodeindex fn cp -@syncodeindex tp cp -@synindex pg cp - -@ifinfo -@node Top, Introduction, (dir), (dir) -@comment node-name, next, previous, up -@top Shared library support for GNU - -This file documents GNU Libtool, a script that allows package developers -to provide generic shared library support. This edition documents -version @value{VERSION}. - -@xref{Reporting bugs}, for information on how to report problems with -libtool. - -@menu -* Introduction:: What the heck is libtool? -* Libtool paradigm:: How libtool's view of libraries is different. -* Using libtool:: Example of using libtool to build libraries. -* Invoking libtool:: Running the @code{libtool} script. -* Integrating libtool:: Using libtool in your own packages. -* Versioning:: Using library interface versions. -* Library tips:: Tips for library interface design. -* Inter-library dependencies:: Libraries that depend on other libraries. -* Dlopened modules:: @code{dlopen}ing libtool-created libraries. -* Using libltdl:: Libtool's portable @code{dlopen} wrapper library. -* Other languages:: Using libtool without a C compiler. -* Troubleshooting:: When libtool doesn't work as advertised. -* Maintaining:: Information used by the libtool maintainer. -* Index:: Full index. - -@detailmenu --- The Detailed Node Listing --- - -Introduction - -* Motivation:: Why does GNU need a libtool? -* Issues:: The problems that need to be addressed. -* Other implementations:: How other people have solved these issues. -* Postmortem:: Learning from past difficulties. - -Using libtool - -* Creating object files:: Compiling object files for libraries. -* Linking libraries:: Creating libraries from object files. -* Linking executables:: Linking object files against libtool libraries. -* Debugging executables:: Running GDB on libtool-generated programs. -* Installing libraries:: Making libraries available to users. -* Installing executables:: Making programs available to users. -* Static libraries:: When shared libraries are not wanted. - -Invoking @code{libtool} - -* Compile mode:: Creating library object files. -* Link mode:: Generating executables and libraries. -* Execute mode:: Debugging libtool-generated programs. -* Install mode:: Making libraries and executables public. -* Finish mode:: Completing a library installation. -* Uninstall mode:: Removing installed executables and libraries. -* Clean mode:: Removing uninstalled executables and libraries. - -Integrating libtool with your package - -* Makefile rules:: Writing @file{Makefile} rules for libtool. -* Using Automake:: Automatically supporting libtool. -* Configuring:: Configuring libtool for a host system. -* Distributing:: What files to distribute with your package. -* Static-only libraries:: Sometimes shared libraries are just a pain. - -Configuring libtool - -* Invoking ltconfig:: @code{ltconfig} command line options. -* ltconfig example:: Manually configuring a @code{libtool}. -* AM_PROG_LIBTOOL:: Configuring @code{libtool} in @file{configure.in}. - -Including libtool in your package - -* Invoking libtoolize:: @code{libtoolize} command line options. -* Autoconf .o macros:: Autoconf macros that set object file names. - -Library interface versions - -* Interfaces:: What are library interfaces? -* Libtool versioning:: Libtool's versioning system. -* Updating version info:: Changing version information before releases. -* Release numbers:: Breaking binary compatibility for aesthetics. - -Tips for interface design - -* C header files:: How to write portable include files. - -Dlopened modules - -* Building modules:: Creating dlopenable objects and libraries. -* Dlpreopening:: Dlopening that works on static platforms. -* Finding the dlname:: Choosing the right file to @code{dlopen}. -* Dlopen issues:: Unresolved problems that need your attention. - -Using libltdl - -* Libltdl interface:: How to use libltdl in your programs. -* Modules for libltdl:: Creating modules that can be @code{dlopen}ed. -* Distributing libltdl:: How to distribute libltdl with your package. -* Module loaders for libltdl:: Creating user defined module loaders. - -Using libtool with other languages - -* C++ libraries:: - -Troubleshooting - -* Libtool test suite:: Libtool's self-tests. -* Reporting bugs:: How to report problems with libtool. - -The libtool test suite - -* Test descriptions:: The contents of the test suite. -* When tests fail:: What to do when a test fails. - -Maintenance notes for libtool - -* New ports:: How to port libtool to new systems. -* Tested platforms:: When libtool was last tested. -* Platform quirks:: Information about different library systems. -* libtool script contents:: Configuration information that libtool uses. -* Cheap tricks:: Making libtool maintainership easier. - -Porting libtool to new systems - -* Information sources:: Where to find relevant documentation -* Porting inter-library dependencies:: Implementation details explained - -Platform quirks - -* References:: Finding more information. -* Compilers:: Creating object files from source files. -* Reloadable objects:: Binding object files together. -* Archivers:: Programs that create static archives. - -@end detailmenu -@end menu - -@end ifinfo - -@node Introduction -@chapter Introduction - -In the past, if a source code package developer wanted to take advantage -of the power of shared libraries, he needed to write custom support code -for each platform on which his package ran. He also had to design a -configuration interface so that the package installer could choose what sort of -libraries were built. - -GNU Libtool simplifies the developer's job by encapsulating both the -platform-specific dependencies, and the user interface, in a single -script. GNU Libtool is designed so that the complete functionality of -each host type is available via a generic interface, but nasty quirks -are hidden from the programmer. - -GNU Libtool's consistent interface is reassuring@dots{} users don't need -to read obscure documentation in order to have their favorite source -package build shared libraries. They just run your package -@code{configure} script (or equivalent), and libtool does all the dirty -work. - -There are several examples throughout this document. All assume the -same environment: we want to build a library, @file{libhello}, in a -generic way. - -@file{libhello} could be a shared library, a static library, or -both@dots{} whatever is available on the host system, as long as libtool -has been ported to it. - -This chapter explains the original design philosophy of libtool. Feel -free to skip to the next chapter, unless you are interested in history, -or want to write code to extend libtool in a consistent way. - -@menu -* Motivation:: Why does GNU need a libtool? -* Issues:: The problems that need to be addressed. -* Other implementations:: How other people have solved these issues. -* Postmortem:: Learning from past difficulties. -@end menu - -@node Motivation -@section Motivation for writing libtool - -@cindex motivation for writing libtool -@cindex design philosophy -Since early 1995, several different GNU developers have recognized the -importance of having shared library support for their packages. The -primary motivation for such a change is to encourage modularity and -reuse of code (both conceptually and physically) in GNU programs. - -Such a demand means that the way libraries are built in GNU packages -needs to be general, to allow for any library type the package installer -might want. The problem is compounded by the absence of a standard -procedure for creating shared libraries on different platforms. - -The following sections outline the major issues facing shared library -support in GNU, and how shared library support could be standardized -with libtool. - -@cindex specifications for libtool -@cindex libtool specifications -The following specifications were used in developing and evaluating this -system: - -@enumerate -@item -The system must be as elegant as possible. - -@item -The system must be fully integrated with the GNU Autoconf and Automake -utilities, so that it will be easy for GNU maintainers to use. However, -the system must not require these tools, so that it can be used by -non-GNU packages. - -@item -Portability to other (non-GNU) architectures and tools is desirable. -@end enumerate - -@node Issues -@section Implementation issues - -@cindex tricky design issues -@cindex design issues -The following issues need to be addressed in any reusable shared library -system, specifically libtool: - -@enumerate -@item -The package installer should be able to control what sort of libraries -are built. - -@item -It can be tricky to run dynamically linked programs whose libraries have -not yet been installed. @code{LD_LIBRARY_PATH} must be set properly (if -it is supported), or programs fail to run. - -@item -The system must operate consistently even on hosts which don't support -shared libraries. - -@item -The commands required to build shared libraries may differ wildly from -host to host. These need to be determined at configure time in -a consistent way. - -@item -It is not always obvious with which suffix a shared library should be -installed. This makes it difficult for @file{Makefile} rules, since they -generally assume that file names are the same from host to host. - -@item -The system needs a simple library version number abstraction, so that -shared libraries can be upgraded in place. The programmer should be -informed how to design the interfaces to the library to maximize binary -compatibility. - -@item -The install @file{Makefile} target should warn the package installer to set -the proper environment variables (@code{LD_LIBRARY_PATH} or equivalent), -or run @code{ldconfig}. -@end enumerate - -@node Other implementations -@section Other implementations - -Even before libtool was developed, many free software packages built and -installed their own shared libraries. At first, these packages were -examined to avoid reinventing existing features. - -Now it is clear that none of these packages have documented the details -of shared library systems that libtool requires. So, other packages -have been more or less abandoned as influences. - -@node Postmortem -@section A postmortem analysis of other implementations - -@cindex other implementations, flaws in -@cindex reusability of library systems -In all fairness, each of the implementations that were examined do the -job that they were intended to do, for a number of different host -systems. However, none of these solutions seem to function well as a -generalized, reusable component. - -@cindex complexity of library systems -Most were too complex to use (much less modify) without understanding -exactly what the implementation does, and they were generally not -documented. - -The main difficulty is that different vendors have different views of -what libraries are, and none of the packages which were examined seemed -to be confident enough to settle on a single paradigm that just -@emph{works}. - -Ideally, libtool would be a standard that would be implemented as series -of extensions and modifications to existing library systems to make them -work consistently. However, it is not an easy task to convince -operating system developers to mend their evil ways, and people want to -build shared libraries right now, even on buggy, broken, confused -operating systems. - -For this reason, libtool was designed as an independent shell script. -It isolates the problems and inconsistencies in library building that -plague @file{Makefile} writers by wrapping the compiler suite on -different platforms with a consistent, powerful interface. - -With luck, libtool will be useful to and used by the GNU community, and -that the lessons that were learned in writing it will be taken up by -designers of future library systems. - -@node Libtool paradigm -@chapter The libtool paradigm - -At first, libtool was designed to support an arbitrary number of library -object types. After libtool was ported to more platforms, a new -paradigm gradually developed for describing the relationship between -libraries and programs. - -@cindex definition of libraries -@cindex libraries, definition of -In summary, ``libraries are programs with multiple entry points, and -more formally defined interfaces.'' - -Version 0.7 of libtool was a complete redesign and rewrite of libtool to -reflect this new paradigm. So far, it has proved to be successful: -libtool is simpler and more useful than before. - -The best way to introduce the libtool paradigm is to contrast it with -the paradigm of existing library systems, with examples from each. It -is a new way of thinking, so it may take a little time to absorb, but -when you understand it, the world becomes simpler. - -@node Using libtool -@chapter Using libtool - -@cindex examples of using libtool -@cindex libtool examples -It makes little sense to talk about using libtool in your own packages -until you have seen how it makes your life simpler. The examples in -this chapter introduce the main features of libtool by comparing the -standard library building procedure to libtool's operation on two -different platforms: - -@table @samp -@item a23 -An Ultrix 4.2 platform with only static libraries. - -@item burger -A NetBSD/i386 1.2 platform with shared libraries. -@end table - -You can follow these examples on your own platform, using the -preconfigured libtool script that was installed with libtool -(@pxref{Configuring}). - -Source files for the following examples are taken from the @file{demo} -subdirectory of the libtool distribution. Assume that we are building a -library, @file{libhello}, out of the files @file{foo.c} and -@file{hello.c}. - -Note that the @file{foo.c} source file uses the @code{cos} math library -function, which is usually found in the standalone math library, and not -the C library (@pxref{Trig Functions, , Trigonometric Functions, libc, -The GNU C Library Reference Manual}). So, we need to add @kbd{-lm} to -the end of the link line whenever we link @file{foo.o} or @file{foo.lo} -into an executable or a library (@pxref{Inter-library dependencies}). - -The same rule applies whenever you use functions that don't appear in -the standard C library@dots{} you need to add the appropriate -@kbd{-l@var{name}} flag to the end of the link line when you link -against those objects. - -After we have built that library, we want to create a program by linking -@file{main.o} against @file{libhello}. - -@menu -* Creating object files:: Compiling object files for libraries. -* Linking libraries:: Creating libraries from object files. -* Linking executables:: Linking object files against libtool libraries. -* Debugging executables:: Running GDB on libtool-generated programs. -* Installing libraries:: Making libraries available to users. -* Installing executables:: Making programs available to users. -* Static libraries:: When shared libraries are not wanted. -@end menu - -@node Creating object files -@section Creating object files - -@cindex compiling object files -@cindex object files, compiling -To create an object file from a source file, the compiler is invoked -with the `-c' flag (and any other desired flags): - -@example -burger$ @kbd{gcc -g -O -c main.c} -burger$ -@end example - -The above compiler command produces an object file, @file{main.o}, from -the source file @file{main.c}. - -For most library systems, creating object files that become part of a -static library is as simple as creating object files that are linked to -form an executable: - -@example -burger$ @kbd{gcc -g -O -c foo.c} -burger$ @kbd{gcc -g -O -c hello.c} -burger$ -@end example - -@cindex position-independent code -@cindex PIC (position-independent code) -Shared libraries, however, may only be built from -@dfn{position-independent code} (PIC). So, special flags must be passed -to the compiler to tell it to generate PIC rather than the standard -position-dependent code. - -@cindex library object file -@cindex @samp{.lo} files -@cindex object files, library -Since this is a library implementation detail, libtool hides the -complexity of PIC compiler flags by using separate library object files -(which end in @samp{.lo} instead of @samp{.o}). On systems without shared -libraries (or without special PIC compiler flags), these library object -files are identical to ``standard'' object files. - -To create library object files for @file{foo.c} and @file{hello.c}, -simply invoke libtool with the standard compilation command as -arguments (@pxref{Compile mode}): - -@example -a23$ @kbd{libtool gcc -g -O -c foo.c} -gcc -g -O -c foo.c -echo timestamp > foo.lo -a23$ @kbd{libtool gcc -g -O -c hello.c} -gcc -g -O -c hello.c -echo timestamp > hello.lo -a23$ -@end example - -Note that libtool creates two files for each invocation. The @samp{.lo} -file is a library object, which may be built into a shared library, and -the @samp{.o} file is a standard object file. On @samp{a23}, the -library objects are just timestamps, because only static libraries are -supported. - -On shared library systems, libtool automatically inserts the PIC -generation flags into the compilation command, so that the library -object and the standard object differ: - -@example -burger$ @kbd{libtool gcc -g -O -c foo.c} -gcc -g -O -c -fPIC -DPIC foo.c -mv -f foo.o foo.lo -gcc -g -O -c foo.c >/dev/null 2>&1 -burger$ @kbd{libtool gcc -g -O -c hello.c} -gcc -g -O -c -fPIC -DPIC hello.c -mv -f hello.o hello.lo -gcc -g -O -c hello.c >/dev/null 2>&1 -burger$ -@end example - -Notice that the second run of GCC has its output discarded. This is -done so that compiler warnings aren't annoyingly duplicated. - -@node Linking libraries -@section Linking libraries - -@pindex ar -Without libtool, the programmer would invoke the @code{ar} command to -create a static library: - -@example -burger$ @kbd{ar cru libhello.a hello.o foo.o} -burger$ -@end example - -@pindex ranlib -But of course, that would be too simple, so many systems require that -you run the @code{ranlib} command on the resulting library (to give it -better karma, or something): - -@example -burger$ @kbd{ranlib libhello.a} -burger$ -@end example - -It seems more natural to use the C compiler for this task, given -libtool's ``libraries are programs'' approach. So, on platforms without -shared libraries, libtool simply acts as a wrapper for the system -@code{ar} (and possibly @code{ranlib}) commands. - -@cindex libtool libraries -@cindex @samp{.la} files -Again, the libtool library name differs from the standard name (it has a -@samp{.la} suffix instead of a @samp{.a} suffix). The arguments to libtool are -the same ones you would use to produce an executable named -@file{libhello.la} with your compiler (@pxref{Link mode}): - -@example -a23$ @kbd{libtool gcc -g -O -o libhello.la foo.o hello.o} -libtool: cannot build libtool library `libhello.la' from non-libtool \ - objects -a23$ -@end example - -Aha! Libtool caught a common error@dots{} trying to build a library -from standard objects instead of library objects. This doesn't matter -for static libraries, but on shared library systems, it is of great -importance. - -So, let's try again, this time with the library object files. Remember -also that we need to add @kbd{-lm} to the link command line because -@file{foo.c} uses the @code{cos} math library function (@pxref{Using -libtool}). - -Another complication in building shared libraries is that we need to -specify the path to the directory in which they (eventually) will be -installed (in this case, @file{/usr/local/lib})@footnote{If you don't -specify an @code{rpath}, then libtool builds a libtool convenience -archive, not a shared library (@pxref{Static libraries}).}: - -@example -a23$ @kbd{libtool gcc -g -O -o libhello.la foo.lo hello.lo \ - -rpath /usr/local/lib -lm} -mkdir @value{objdir} -ar cru @value{objdir}/libhello.a foo.o hello.o -ranlib @value{objdir}/libhello.a -creating libhello.la -a23$ -@end example - -Now, let's try the same trick on the shared library platform: - -@example -burger$ @kbd{libtool gcc -g -O -o libhello.la foo.lo hello.lo \ - -rpath /usr/local/lib -lm} -mkdir @value{objdir} -ld -Bshareable -o @value{objdir}/libhello.so.0.0 foo.lo hello.lo -lm -ar cru @value{objdir}/libhello.a foo.o hello.o -ranlib @value{objdir}/libhello.a -creating libhello.la -burger$ -@end example - -Now that's significantly cooler@dots{} libtool just ran an obscure -@code{ld} command to create a shared library, as well as the static -library. - -@cindex @file{@value{objdir}} subdirectory -Note how libtool creates extra files in the @file{@value{objdir}} -subdirectory, rather than the current directory. This feature is to -make it easier to clean up the build directory, and to help ensure that -other programs fail horribly if you accidentally forget to use libtool -when you should. - -@node Linking executables -@section Linking executables - -@cindex linking against installed libraries -If you choose at this point to @dfn{install} the library (put it in a -permanent location) before linking executables against it, then you -don't need to use libtool to do the linking. Simply use the appropriate -@samp{-L} and @samp{-l} flags to specify the library's location. - -@cindex buggy system linkers -Some system linkers insist on encoding the full directory name of each -shared library in the resulting executable. Libtool has to work around -this misfeature by special magic to ensure that only permanent directory -names are put into installed executables. - -@cindex security problems with buggy linkers -@cindex bugs, subtle ones caused by buggy linkers -The importance of this bug must not be overlooked: it won't cause -programs to crash in obvious ways. It creates a security hole, -and possibly even worse, if you are modifying the library source code -after you have installed the package, you will change the behaviour of -the installed programs! - -So, if you want to link programs against the library before you install -it, you must use libtool to do the linking. - -@cindex linking against uninstalled libraries -Here's the old way of linking against an uninstalled library: - -@example -burger$ @kbd{gcc -g -O -o hell.old main.o libhello.a -lm} -burger$ -@end example - -Libtool's way is almost the same@footnote{However, you should avoid using -@samp{-L} or @samp{-l} flags to link against an uninstalled libtool -library. Just specify the relative path to the @samp{.la} file, such as -@file{../intl/libintl.la}. This is a design decision to eliminate any -ambiguity when linking against uninstalled shared libraries.} -(@pxref{Link mode}): - -@example -a23$ @kbd{libtool gcc -g -O -o hell main.o libhello.la -lm} -gcc -g -O -o hell main.o ./@value{objdir}/libhello.a -lm -a23$ -@end example - -That looks too simple to be true. All libtool did was transform -@file{libhello.la} to @file{./@value{objdir}/libhello.a}, but remember -that @samp{a23} has no shared libraries. - -On @samp{burger} the situation is different: - -@example -burger$ @kbd{libtool gcc -g -O -o hell main.o libhello.la -lm} -gcc -g -O -o @value{objdir}/hell main.o -L./@value{objdir} -R/usr/local/lib -lhello -lm -creating hell -burger$ -@end example - -@cindex linking with installed libtool libraries - -Now assume @file{libhello.la} had already been installed, and you want -to link a new program with it. You could figure out where it lives by -yourself, then run: - -@example -burger$ @kbd{gcc -g -O -o test test.o -L/usr/local/lib -lhello} -@end example - -However, unless @file{/usr/local/lib} is in the standard library search -path, you won't be able to run @code{test}. However, if you use libtool -to link the already-installed libtool library, it will do The Right -Thing (TM) for you: - -@example -burger$ @kbd{libtool gcc -g -O -o test test.o /usr/local/lib/libhello.la} -gcc -g -O -o @value{objdir}/test test.o -Wl,--rpath --Wl,/usr/local/lib /usr/local/lib/libhello.a -lm -creating test -burger$ -@end example - -Note that libtool added the necessary run-time path flag, as well as -@samp{-lm}, the library libhello.la depended upon. Nice, huh? - -Since libtool created a wrapper script, you should use libtool to -install it and debug it too. However, since the program does not depend -on any uninstalled libtool library, it is probably usable even without -the wrapper script. Libtool could probably be made smarter to avoid the -creation of the wrapper script in this case, but this is left as an -exercise for the reader. - - -@cindex wrapper scripts for programs -@cindex program wrapper scripts -Notice that the executable, @code{hell}, was actually created in the -@file{@value{objdir}} subdirectory. Then, a wrapper script was created -in the current directory. - -On NetBSD 1.2, libtool encodes the installation directory of -@file{libhello}, by using the @samp{-R/usr/local/lib} compiler flag. -Then, the wrapper script guarantees that the executable finds the -correct shared library (the one in @file{./@value{objdir}}) until it is -properly installed. - -Let's compare the two different programs: - -@example -burger$ @kbd{time ./hell.old} -Welcome to GNU Hell! -** This is not GNU Hello. There is no built-in mail reader. ** - 0.21 real 0.02 user 0.08 sys -burger$ @kbd{time ./hell} -Welcome to GNU Hell! -** This is not GNU Hello. There is no built-in mail reader. ** - 0.63 real 0.09 user 0.59 sys -burger$ -@end example - -The wrapper script takes significantly longer to execute, but at least -the results are correct, even though the shared library hasn't been -installed yet. - -So, what about all the space savings that shared libraries are supposed -to yield? - -@example -burger$ @kbd{ls -l hell.old libhello.a} --rwxr-xr-x 1 gord gord 15481 Nov 14 12:11 hell.old --rw-r--r-- 1 gord gord 4274 Nov 13 18:02 libhello.a -burger$ @kbd{ls -l @value{objdir}/hell @value{objdir}/libhello.*} --rwxr-xr-x 1 gord gord 11647 Nov 14 12:10 @value{objdir}/hell --rw-r--r-- 1 gord gord 4274 Nov 13 18:44 @value{objdir}/libhello.a --rwxr-xr-x 1 gord gord 12205 Nov 13 18:44 @value{objdir}/libhello.so.0.0 -burger$ -@end example - -Well, that sucks. Maybe I should just scrap this project and take up -basket weaving. - -Actually, it just proves an important point: shared libraries incur -overhead because of their (relative) complexity. In this situation, the -price of being dynamic is eight kilobytes, and the payoff is about four -kilobytes. So, having a shared @file{libhello} won't be an advantage -until we link it against at least a few more programs. - -@node Debugging executables -@section Debugging executables - -If @file{hell} was a complicated program, you would certainly want to -test and debug it before installing it on your system. In the above -section, you saw how the libtool wrapper script makes it possible to run -the program directly, but unfortunately, this mechanism interferes with -the debugger: - -@example -burger$ @kbd{gdb hell} -GDB is free software and you are welcome to distribute copies of it - under certain conditions; type "show copying" to see the conditions. -There is no warranty for GDB; type "show warranty" for details. -GDB 4.16 (i386-unknown-netbsd), (C) 1996 Free Software Foundation, Inc. - -"hell": not in executable format: File format not recognized - -(gdb) @kbd{quit} -burger$ -@end example - -Sad. It doesn't work because GDB doesn't know where the executable -lives. So, let's try again, by invoking GDB directly on the executable: - -@example -burger$ @kbd{gdb @value{objdir}/hell} -trick:/home/src/libtool/demo$ gdb .libs/hell -GDB is free software and you are welcome to distribute copies of it - under certain conditions; type "show copying" to see the conditions. -There is no warranty for GDB; type "show warranty" for details. -GDB 4.16 (i386-unknown-netbsd), (C) 1996 Free Software Foundation, Inc. -(gdb) @kbd{break main} -Breakpoint 1 at 0x8048547: file main.c, line 29. -(gdb) @kbd{run} -Starting program: /home/src/libtool/demo/.libs/hell -/home/src/libtool/demo/.libs/hell: can't load library 'libhello.so.2' - -Program exited with code 020. -(gdb) @kbd{quit} -burger$ -@end example - -Argh. Now GDB complains because it cannot find the shared library that -@file{hell} is linked against. So, we must use libtool in order to -properly set the library path and run the debugger. Fortunately, we can -forget all about the @file{@value{objdir}} directory, and just run it on -the executable wrapper (@pxref{Execute mode}): - -@example -burger$ @kbd{libtool gdb hell} -GDB is free software and you are welcome to distribute copies of it - under certain conditions; type "show copying" to see the conditions. -There is no warranty for GDB; type "show warranty" for details. -GDB 4.16 (i386-unknown-netbsd), (C) 1996 Free Software Foundation, Inc. -(gdb) @kbd{break main} -Breakpoint 1 at 0x8048547: file main.c, line 29. -(gdb) @kbd{run} -Starting program: /home/src/libtool/demo/.libs/hell - -Breakpoint 1, main (argc=1, argv=0xbffffc40) at main.c:29 -29 printf ("Welcome to GNU Hell!\n"); -(gdb) @kbd{quit} -The program is running. Quit anyway (and kill it)? (y or n) @kbd{y} -burger$ -@end example - -@node Installing libraries -@section Installing libraries - -@pindex strip -Installing libraries on a non-libtool system is quite -straightforward@dots{} just copy them into place:@footnote{Don't -accidentally strip the libraries, though, or they will be unusable.} - -@pindex su -@example -burger$ @kbd{su} -Password: @kbd{********} -burger# @kbd{cp libhello.a /usr/local/lib/libhello.a} -burger# -@end example - -Oops, don't forget the @code{ranlib} command: - -@example -burger# @kbd{ranlib /usr/local/lib/libhello.a} -burger# -@end example - -@pindex install -Libtool installation is quite simple, as well. Just use the -@code{install} or @code{cp} command that you normally would -(@pxref{Install mode}): - -@example -a23# @kbd{libtool cp libhello.la /usr/local/lib/libhello.la} -cp libhello.la /usr/local/lib/libhello.la -cp @value{objdir}/libhello.a /usr/local/lib/libhello.a -ranlib /usr/local/lib/libhello.a -a23# -@end example - -Note that the libtool library @file{libhello.la} is also installed, to -help libtool with uninstallation (@pxref{Uninstall mode}) and linking -(@pxref{Linking executables}) and to help programs with dlopening -(@pxref{Dlopened modules}). - -Here is the shared library example: - -@example -burger# @kbd{libtool install -c libhello.la /usr/local/lib/libhello.la} -install -c @value{objdir}/libhello.so.0.0 /usr/local/lib/libhello.so.0.0 -install -c libhello.la /usr/local/lib/libhello.la -install -c @value{objdir}/libhello.a /usr/local/lib/libhello.a -ranlib /usr/local/lib/libhello.a -burger# -@end example - -@cindex stripping libraries -@cindex libraries, stripping -It is safe to specify the @samp{-s} (strip symbols) flag if you use a -BSD-compatible install program when installing libraries. -Libtool will either ignore the @samp{-s} flag, or will run a program -that will strip only debugging and compiler symbols from the library. - -Once the libraries have been put in place, there may be some additional -configuration that you need to do before using them. First, you must -make sure that where the library is installed actually agrees with the -@samp{-rpath} flag you used to build it. - -@cindex postinstallation -@cindex installation, finishing -@cindex libraries, finishing installation -Then, running @samp{libtool -n --finish @var{libdir}} can give you -further hints on what to do (@pxref{Finish mode}): - -@example -burger# @kbd{libtool -n --finish /usr/local/lib} -PATH="$PATH:/sbin" ldconfig -m /usr/local/lib ------------------------------------------------------------------ -Libraries have been installed in: - /usr/local/lib - -To link against installed libraries in a given directory, LIBDIR, -you must use the `-LLIBDIR' flag during linking. - - You will also need to do one of the following: - - add LIBDIR to the `LD_LIBRARY_PATH' environment variable - during execution - - add LIBDIR to the `LD_RUN_PATH' environment variable - during linking - - use the `-RLIBDIR' linker flag - -See any operating system documentation about shared libraries for -more information, such as the ld and ld.so manual pages. ------------------------------------------------------------------ -burger# -@end example - -After you have completed these steps, you can go on to begin using the -installed libraries. You may also install any executables that depend -on libraries you created. - -@node Installing executables -@section Installing executables - -If you used libtool to link any executables against uninstalled libtool -libraries (@pxref{Linking executables}), you need to use libtool to -install the executables after the libraries have been installed -(@pxref{Installing libraries}). - -So, for our Ultrix example, we would run: - -@example -a23# libtool install -c hell /usr/local/bin/hell -install -c hell /usr/local/bin/hell -a23# -@end example - -On shared library systems, libtool just ignores the wrapper script and -installs the correct binary: - -@example -burger# libtool install -c hell /usr/local/bin/hell -install -c @value{objdir}/hell /usr/local/bin/hell -burger# -@end example - -@node Static libraries -@section Linking static libraries - -@cindex static linking -@cindex convenience libraries -Why return to @code{ar} and @code{ranlib} silliness when you've had a -taste of libtool? Well, sometimes it is desirable to create a static -archive that can never be shared. The most frequent case is when you -have a set of object files that you use to build several different -programs. You can create a ``convenience library'' out of those -objects, and link programs with the library, instead of listing all -object files for every program. This technique is often used to -overcome GNU automake's lack of support for linking object files built -from sources in other directories, because it supports linking with -libraries from other directories. This limitation applies to GNU -automake up to release 1.4; newer releases should support sources in -other directories. - -If you just want to link this convenience library into programs, then -you could just ignore libtool entirely, and use the old @code{ar} and -@code{ranlib} commands (or the corresponding GNU automake -@samp{_LIBRARIES} rules). You can even install a convenience library -(but you probably don't want to) using libtool: - -@example -burger$ @kbd{libtool ./install-sh -c libhello.a /local/lib/libhello.a} -./install-sh -c libhello.a /local/lib/libhello.a -ranlib /local/lib/libhello.a -burger$ -@end example - -Using libtool for static library installation protects your library from -being accidentally stripped (if the installer used the @samp{-s} flag), -as well as automatically running the correct @code{ranlib} command. - -But libtool libraries are more than just collections of object files: -they can also carry library dependency information, which old archives -do not. If you want to create a libtool static convenience library, you -can omit the @samp{-rpath} flag and use @samp{-static} to indicate that -you're only interested in a static library. When you link a program -with such a library, libtool will actually link all object files and -dependency libraries into the program. - -If you omit both @samp{-rpath} and @samp{-static}, libtool will create a -convenience library that can be used to create other libtool -libraries, even shared ones. Just like in the static case, the library -behaves as an alias to a set of object files and dependency libraries, -but in this case the object files are suitable for inclusion in shared -libraries. But be careful not to link a single convenience library, -directly or indirectly, into a single program or library, otherwise you -may get errors about symbol redefinitions. - +\input texinfo @c -*-texinfo-*- + +@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 -@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 - -int main() @{ - /* ... */ - LTDL_SET_PRELOADED_SYMBOLS(); - /* ... */ -@} -@end example -@end defmac - -@deftypefun int lt_dladdsearchdir (const char *@var{search_dir}) -Add the search directory @var{search_dir} to the user-defined library -search path. Return 0 on success. -@end deftypefun - -@deftypefun int lt_dlsetsearchpath (const char *@var{search_path}) -Replace the current user-defined library search path with -@var{search_path}, which must be a colon-separated list of absolute -directories. Return 0 on success. -@end deftypefun - -@deftypefun {const char *} lt_dlgetsearchpath (void) -Return the current user-defined library search path. -@end deftypefun - -@deftypefun {const lt_dlinfo *} lt_dlgetinfo (lt_dlhandle @var{handle}) -Return a pointer to a struct that contains some information about -the module @var{handle}. The contents of the struct must not be modified. -Return @code{NULL} on failure. -@end deftypefun - -@deftypefun int lt_dlforeach (int (*@var{func})(lt_dlhandle @var{handle}, lt_ptr_t @var{data}), lt_ptr_t @var{data}) -For each loaded module call the function @var{func}. The argument -@var{handle} is the handle of one of the loaded modules, @var{data} is -the @var{data} argument passed to @code{lt_dlforeach}. -As soon as @var{func} returns a non-zero value for one of the handles, -@code{lt_dlforeach} will stop calling @var{func} and immediately return 1. -Otherwise 0 is returned. -@end deftypefun - -@deftypevar {lt_ptr_t (*} lt_dlmalloc ) (size_t @var{size}) -@deftypevarx {void (*} lt_dlfree ) (lt_ptr_t @var{ptr}) -These variables are set to @code{malloc} and @code{free}, by default, -but you can set them to any other functions that provides equivalent -functionality. However, you must not modify their values after calling -any libltdl function other than @code{lt_dlpreopen_default} or the macro -@code{LTDL_SET_PRELOADED_SYMBOLS}. -@end deftypevar - -@node Modules for libltdl -@section Creating modules that can be @code{dlopen}ed - -Libtool modules are like normal libtool libraries with a few exceptions: - -You have to link the module with libtool's @samp{-module} switch, -and you should link any program that is intended to dlopen the module with -@samp{-dlopen modulename.la} so that libtool can dlpreopen the module -on platforms which don't support dlopening. If the module depends on any -other libraries, make sure you specify them either when you link the module -or when you link programs that dlopen it. -If you want to disable @pxref{Versioning} for a specific module -you should link it with the @samp{-avoid-version} switch. -Note that libtool modules don't need to have a "lib" prefix. -However, automake 1.4 or higher is required to build such modules. - -Usually a set of modules provide the same interface, i.e, exports the same -symbols, so that a program can dlopen them without having to know more -about their internals. -In order to avoid symbol conflicts all exported symbols must be prefixed -with "modulename_LTX_" (@samp{modulename} is the name of the module). -Internal symbols must be named in such a way that they won't conflict -with other modules, for example, by prefixing them with "_modulename_". -Although some platforms support having the same symbols defined more than -once it is generally not portable and it makes it impossible to dlpreopen -such modules. libltdl will automatically cut the prefix off to get -the real name of the symbol. Additionally, it supports modules which -don't use a prefix so that you can also dlopen non-libtool modules. - -@file{foo1.c} gives an example of a portable libtool module. -Exported symbols are prefixed with "foo1_LTX_", internal symbols -with "_foo1_". Aliases are defined at the beginning so that the code -is more readable. - -@example -/* aliases for the exported symbols */ -#define foo foo1_LTX_foo -#define bar foo1_LTX_bar - -/* a global variable definition */ -int bar = 1; - -/* a private function */ -int _foo1_helper() @{ - return bar; -@} - -/* an exported function */ -int foo() @{ - return _foo_helper(); -@} -@end example - -@noindent -The @file{Makefile.am} contains the necessary rules to build the -module @file{foo1.la}: - -@example -... -lib_LTLIBRARIES = foo1.la - -foo1_la_SOURCES = foo1.c -foo1_la_LDFLAGS = -module -... -@end example - -@node Distributing libltdl -@section How to distribute libltdl with your package - -Even though libltdl is installed together with libtool, you may wish to -include libltdl in the distribution of your package, for the convenience -of users of your package that don't have libtool or libltdl installed. -In this case, you must decide whether to manually add the @code{ltdl} -objects to your package, or else which flavor of libltdl you want to use: -a convenience library or an installable libtool library. - -The most simplistic way to add @code{ltdl} to your package is to copy -the source files, @file{ltdl.c} and @file{ltdl.h}, to a source directory -withing your package and to build and link them along with the rest of -your sources. To help you do this, the m4 macros for autoconf are -available in @file{ltdl.m4}. You must ensure that they are available in -@file{aclocal.m4} before you run autoconf -- by appending the contents -of @file{ltdl.m4} to @file{acinclude.m4}, if you are using automake, or -to @file{aclocal.m4} if you are not. Having made the macros available, -you must add a call to the @samp{AC_LIB_LTDL} macro to your package's -@file{configure.in} to perform the configure time checks required to -build @file{ltdl.o} correctly. This method has problems if you then try -to link the package binaries with an installed libltdl, or a library -which depends on libltdl: you may have problems with duplicate symbol -definitions. - -One advantage of the convenience library is that it is not installed, so -the fact that you use libltdl will not be apparent to the user, and it -will not overwrite a pre-installed version of libltdl a user might have. -On the other hand, if you want to upgrade libltdl for any reason -(e.g. a bugfix) you'll have to recompile your package instead of just -replacing an installed version of libltdl. -However, if your programs or libraries are linked with other libraries -that use such a pre-installed version of libltdl, you may get linker -errors or run-time crashes. Another problem is that you cannot link the -convenience library into more than one libtool library, then link a -single program with these libraries, because you may get duplicate -symbols. In general you can safely use the convenience library in programs -which don't depend on other libraries that might use libltdl too. -In order to enable this flavor of libltdl, you should add the -line @samp{AC_LIBLTDL_CONVENIENCE} to your @file{configure.in}, -@emph{before} @samp{AM_PROG_LIBTOOL}. - -In order to select the installable version of libltdl, you should add a -call of the macro @samp{AC_LIBLTDL_INSTALLABLE} to your -@file{configure.in} @emph{before} @samp{AM_PROG_LIBTOOL}. This macro -will check whether libltdl is already installed and, if not, request the -libltdl embedded in your package to be built and installed. Note, -however, that no version checking is performed. The user may override -the test and determine that the libltdl embedded must be installed, -regardless of the existence of another version, using the configure -switch @samp{--enable-ltdl-install}. - -In order to embed libltdl into your package, just add @samp{--ltdl} to -the @code{libtoolize} command line. It will copy the libltdl sources -to a subdirectory @samp{libltdl} in your package. -Both macros accept an optional argument to specify the location -of the @samp{libltdl} directory. By the default both macros assume that it -is @samp{$@{top_builddir@}/libltdl}. - -Whatever macro you use, it is up to you to ensure that your -@file{configure.in} will configure libltdl, using -@samp{AC_CONFIG_SUBDIRS}, and that your @file{Makefile}s will start -sub-makes within libltdl's directory, using automake's @var{SUBDIRS}, -for example. Both macros define the shell variables @var{LIBLTDL}, to -the link flag that you should use to link with libltdl, and -@var{INCLTDL}, to the preprocessor flag that you should use to compile -with programs that include @file{ltdl.h}. It is up to you to use -@samp{AC_SUBST} to ensure that this variable will be available in -@file{Makefile}s, or add them to variables that are @samp{AC_SUBST}ed by -default, such as @var{LIBS} and @var{CPPFLAGS}. - -If you're using the convenience libltdl, @var{LIBLTDL} will be the -pathname for the convenience version of libltdl and @var{INCLTDL} will be -@samp{-I} followed by the directory that contains libltdl, both starting -with @samp{$@{top_builddir@}/}. - -If you request an installed version of libltdl and one is -found@footnote{Even if libltdl is installed, -@samp{AC_LIBLTDL_INSTALLABLE} may fail to detect it, if libltdl depends -on symbols provided by libraries other than the C library. In this -case, it will needlessly build and install libltdl.}, @var{LIBLTDL} will -be set to @samp{-lltdl} and @var{INCLTDL} will be empty (which is just a -blind assumption that @file{ltdl.h} is somewhere in the include path if -libltdl is in the library path). If an installable version of libltdl -must be built, its pathname, starting with @samp{$@{top_builddir@}/}, -will be stored in @var{LIBLTDL}, and @var{INCLTDL} will be set just like -in the case of convenience library. - -So, when you want to link a program with libltdl, be it a convenience, -installed or installable library, just compile with @samp{$(INCLTDL)} -and link it with @samp{$(LIBLTDL)}, using libtool. - -You should probably also add @samp{AC_LIBTOOL_DLOPEN} to your -@file{configure.in} @emph{before} @samp{AM_PROG_LIBTOOL}, otherwise -libtool will assume no dlopening mechanism is supported, and revert to -dlpreopening, which is probably not what you want. - -Avoid using the @code{-static} or @code{-all-static} switches when -linking programs with libltdl. This will not work on all platforms, -because the dlopening functions may not be available for static linking. - -The following example shows you how to embed the convenience libltdl in -your package. In order to use the installable variant just replace -@samp{AC_LIBLTDL_CONVENIENCE} with @samp{AC_LIBLTDL_INSTALLABLE}. We -assume that libltdl was embedded using @samp{libtoolize --ltdl}. - -configure.in: -@example -... -dnl Enable building of the convenience library -dnl and set LIBLTDL accordingly -AC_LIBLTDL_CONVENIENCE -dnl Substitute INCLTDL and LIBLTDL in the Makefiles -AC_SUBST(INCLTDL) -AC_SUBST(LIBLTDL) -dnl Check for dlopen support -AC_LIBTOOL_DLOPEN -dnl Configure libtool -AM_PROG_LIBTOOL -dnl Configure libltdl -AC_CONFIG_SUBDIRS(libltdl) -... -@end example - -Makefile.am: -@example -... -SUBDIRS = libltdl - -INCLUDES = $(INCLTDL) - -myprog_LDFLAGS = -export-dynamic -# The quotes around -dlopen below fool automake into accepting it -myprog_LDADD = $(LIBLTDL) "-dlopen" self "-dlopen" libfoo.la -myprog_DEPENDENCIES = $(LIBLTDL) libfoo.la -... -@end example - - -@node Module loaders for libltdl -@section How to create and register new module loaders - -Sometimes libltdl's many ways of gaining access to modules are not -sufficient for the purposes of a project. You can write your own -loader, and register it with libltdl so that @code{lt_dlopen} will be -able to use it. - -Writing a loader involves writing at least three functions which can be -called by @code{lt_dlopen}, @code{lt_dlsym} and @code{lt_dlclose}. -Optionally, you can provide a finalisation function to perform any -cleanup operations when @code{lt_dlexit} executes, and a symbol prefix -string which will be prepended to any symbols passed to @code{lt_dlsym}. -These functions must match the function pointer types below, after -which they can be allocated to an instance of @code{lt_user_dlloader} -and registered. - -Registering the loader requires that you choose a name for it, so that it -can be recognised by @code{lt_find_dlloader} and removed with -@code{lt_remove_dlloader}. The name you choose must be unique, and not -already in use by libltdl's builtin loaders: - -@table @asis -@item "dlopen" -The system dynamic library loader, if one exists. -@item "dld" -The @sc{gnu} dld loader, if @file{libdld} wasinstalled when libltdl was -built. -@item "dlpreload" -The loader for @code{lt_dlopen}ing of preloaded static modules. -@end table - -The prefix "dl" is reserved for loaders supplied with future versions of -libltdl, so you should not use that for your own loader names. - -@noindent -The following types are defined in @file{ltdl.h}: - -@deftp {Type} lt_module_t -@code{lt_module_t} is a dlloader dependent module. -The dynamic module loader extensions communicate using these low -level types. -@end deftp - -@deftp {Type} lt_dlloader_t -@code{lt_dlloader_t} is a handle for module loader types. -@end deftp - -@deftypefn {Type} {struct} lt_user_dlloader @{@w{const char *@var{sym_prefix};} @w{lt_module_open_t *@var{module_open};} @w{lt_module_close_t *@var{module_close};} @w{lt_find_sym_t *@var{find_sym};} @w{lt_dlloader_exit_t *@var{dlloader_exit};} @} -If you want to define a new way to open dynamic modules, and have the -@code{lt_dlopen} @sc{api} use it, you need to instantiate one of these -structures and pass it to @code{lt_add_dlloader}. -@end deftypefn - -@deftypefn {Type} lt_module_t lt_module_open_t (@w{const char *@var{filename}}) -The type of the loader function for an @code{lt_dlloader_t} module -loader. Implementation of such a function should attempt to load the -named module, and return an @code{lt_module_t} suitable for passing in -to the associated @code{lt_module_close_t} and @code{lt_sym_find_t} -function pointers. If the function fails it should return NULL, and set -the error message with @code{lt_dlseterror}. -@end deftypefn - -@deftypefn {Type} int lt_module_close_t (@w{lt_module_t @var{module}}) -The type of the unloader function for a user defined module loader. -Implementatation of such a function should attempt to release -any resources tied up by the @var{module} module, and then unload it -from memory. If the function fails for some reason, set the error -message with @code{lt_dlseterror} and return non-zero. -@end deftypefn - -@deftypefn {Type} lt_ptr_t lt_find_sym_t (@w{lt_module_t @var{module},} @w{const char *@var{symbol}}) -The type of the symbol lookup function for a user defined module loader. -Implementation of such a function should return the address of the named -@var{symbol} in the module @var{module}, or else set the error message -with @code{lt_dlseterror} and return NULL if lookup fails. -@end deftypefn - -@deftypefn {Type} int lt_dlloader_exit_t (void) -The type of the finalisation function for a user defined module loader. -Implementation of such a function should free any resources associated -with the loader. If non-NULL, the function will be called by -@code{lt_dlexit}. -@end deftypefn - -For example: - -@example -int -register_myloader (void) -@{ - lt_user_dlloader dlloader; - - /* User modules are responsible for their own initialisation. */ - if (myloader_init () != 0) - return MYLOADER_INIT_ERROR; - - dlloader.sym_prefix = NULL; - dlloader.module_open = myloader_open; - dlloader.module_close = myloader_close; - dlloader.find_sym = myloader_find_sym. - dlloader.dlloader_exit = myloader_exit; - - /* Add my loader as the default module loader. */ - if (lt_add_dlloader (lt_next_dlloader (NULL), &dlloader, "myloader") != 0) - return ERROR; - - return OK; -@} -@end example - -Note that if there is any initialisation required for the loader, -it must be performed manually before the loader is registered -- -libltdl doesn't handle user loader initialisation. - -Finalisation @emph{is} handled by libltdl however, and it is important -to ensure the @code{dlloader_exit} callback releases any resources claimed -during the initialisation phase. - -@page -@noindent -libltdl provides the following functions for writing your own module -loaders: - -@deftypefun int lt_add_dlloader (@w{lt_dlloader_t *@var{place},} @w{lt_user_dlloader *@var{dlloader},} @w{const char *@var{loader_name}}) -Add a new module loader to the list of all loaders, either as the -last loader (if @var{place} is @code{NULL}), else immediately before the -loader passed as @var{place}. @var{loader_name} will be returned by -@code{lt_dlloader_name} if it is subsequently passed a newly -registered loader. These @var{loader_name}s must be unique, or -@code{lt_remove_dlloader} and @code{lt_find_dlloader} cannot -work. Returns 0 for success. - -@example -@{ - /* Make myloader be the last one. */ - if (lt_add_dlloader (NULL, myloader) != 0) - perror (lt_dlerror ()); -@} -@end example -@end deftypefun - -@deftypefun int lt_remove_dlloader (@w{const char *@var{loader_name}}) -Remove the loader identified by the unique name, @var{loader_name}. -Before this can succeed, all modules opened by the named loader must -have been closed. Returns 0 for success, otherwise an error message can -be obtained from @code{lt_dlerror}. - -@example -@{ - /* Remove myloader. */ - if (lt_remove_dlloader ("myloader") != 0) - perror (lt_dlerror ()); -@} -@end example -@end deftypefun - -@deftypefun lt_dlloader_t *lt_next_dlloader (@w{lt_dlloader_t *@var{place}}) -Iterate over the module loaders, returning the first loader if @var{place} is -@code{NULL}, and the next one on subsequent calls. The handle is for use with -@code{lt_add_dlloader}. - -@example -@{ - /* Make myloader be the first one. */ - if (lt_add_dlloader (lt_next_dlloader (NULL), myloader) != 0) - return ERROR; -@} -@end example -@end deftypefun - -@deftypefun lt_dlloader_t *lt_find_dlloader (@w{const char *@var{loader_name}}) -Return the first loader with a matching @var{loader_name} identifier, or else -@code{NULL}, if the identifier is not found. - -The identifiers which may be used by ltdl itself, if the host -architecture supports them are @dfn{dlopen}@footnote{This is used for -the host dependent module loading @sc{api} -- @code{shl_load} and -@code{LoadLibrary} for example}, @dfn{dld} and @dfn{dlpreload}. - -@example -@{ - /* Add a user loader as the next module loader to be tried if - the standard dlopen loader were to fail when lt_dlopening. */ - if (lt_add_dlloader (lt_find_dlloader ("dlopen"), myloader) != 0) - return ERROR; -@} -@end example -@end deftypefun - -@deftypefun char *lt_dlloader_name (@w{lt_dlloader_t *@var{place}}) -Return the identifying name of @var{PLACE}, as obtained from -@code{lt_next_dlloader} or @code{lt_find_dlloader}. If this function fails, -it will return @code{NULL} and set an error for retrieval with -@code{lt_dlerror}. -@end deftypefun - -@subsection Error handling within user module loaders - -@deftypefun int lt_dladderror (@w{const char *@var{diagnostic}}) -This function allows you to integrate your own error messages into -@code{lt_dlerror}. Pass in a suitable diagnostic message for return by -@code{lt_dlerror}, and an error identifier for use with -@code{lt_dlseterror} is returned. - -If the allocation of an identifier fails, this function returns -1. - -@example -int myerror = lt_dladderror ("Doh!"); -if (myerror < 0) - perror (lt_dlerror ()); -@end example -@end deftypefun - -@deftypefun int lt_dlseterror (@w{int @var{errorcode}}) -When writing your own module loaders, you should use this function to -raise errors so that they are propogated through the @code{lt_dlerror} -interface. All of the standard errors used by libltdl are declared in -@file{ltdl.h}, or you can add more of your own with -@code{lt_dladderror}. This function returns 0 on success. - -@example -if (lt_dlseterror (LTDL_ERROR_NO_MEMORY) != 0) - perror (lt_dlerror ()); -@end example -@end deftypefun - -@node Other languages -@chapter Using libtool with other languages -@cindex C, not using -@cindex languages, non-C -@cindex C++, using - -Libtool was first implemented in order to add support for writing shared -libraries in the C language. However, over time, libtool is being -integrated with other languages, so that programmers are free to reap -the benefits of shared libraries in their favorite programming language. - -This chapter describes how libtool interacts with other languages, -and what special considerations you need to make if you do not use C. - -@menu -* Configuration tags:: -* C++ libraries:: -@end menu - -@node Configuration tags -@section Configuration tags -@cindex Configuration tags -@cindex tags - -A single libtool script may support multiple configurations. By -default, it will only support C compilation, but additional -configuration tags can be created, using @samp{ltconfig --add-tag}, so -that libtool can support other compilers. Such configuration tags can -be used to select native compilers instead of cross ones, or compilers -of other languages. - -For example, in order to create a tag for a C++ compiler @samp{CC}, you -could run: - -@example -$ @kbd{LTCC=gcc CC=c++ CFLAGS=-g CPPFLAGS=-Dfoo \} -> @kbd{./ltconfig -o libtool --add-tag=CXX ltcf-cxx.sh} -@end example - -@samp{ltcf-cxx.sh} is a shell script fragment that configures C++ -specific variables that get placed within the appended configuration -tag. Another shell script called @samp{ltcf-c.sh} that contains C -compiler configurations also exists but it should not be used by the -user. It is used internally by the ltconfig script. - -Note that you should set @var{LTCC} to a valid C compiler, because -libtool may need to compile additional C sources internally. Note also -that, although @samp{CC} is not a C compiler, you should use variables -such as @var{CC}, @var{CFLAGS} and @var{CPPFLAGS} to tell libtool which -flags to use when compiling test programs. - -You can use existing compiler/language specific shell script fragments, -such as @samp{ltcf-cxx.sh}, as a reference for other compilers/languages -you would like libtool to support. - -A potential problem may occur if you use variables when setting -@var{LTCC} and @var{CC}. For example, a problem will occur if you do -the following: - -@example -$ @kbd{LTCC=$CC CC=$CXX ./ltconfig -o libtool --add-tag=CXX ltcf-cxx.sh} -@end example - -In this example, @var{CC} is set to the C++ compiler and LTCC is set to -the compiler pointed to by @var{$CC}. However, @var{CC} was previously -set to the C++ compiler @var{$CXX}, which causes LTCC to be set to the -C++ compiler @var{$CXX}, too. This is a problem because LTCC must be a -valid C compiler, not a C++ compiler for example. - -If @samp{ltconfig} is unable to determine the host type then you must -explicitly provide a host when invoking @samp{ltconfig}. This is -typically necessary for new very platforms and many cross-compiled -platforms. For example, assuming that your host is @samp{i386-nto} then -@samp{ltconfig} could be invoked as follows: - -@example -$ @kbd{LTCC=$CC CC=$CXX ./ltconfig -o libtool \} -> @kbd{--add-tag=CXX ltcf-cxx.sh i386-nto} -@end example - -After a configuration tag has been added using the @samp{--add-tag} -option, whenever you want to compile or link a library using -@samp{c++}, you should run: - -@example -$ @kbd{./libtool --mode=compile c++ -c test.cc} -@end example - -Libtool will automatically detect the appropriate tagged configuration -to use by matching the compiler used in the above command with the one -the tagged configuration was configured with. - -The tagged configuration that libtool uses can be explicitly specified -by using the @samp{--tag} option as follows: - -@example -$ @kbd{./libtool --tag=CXX --mode=compile c++ -c test.cc} -@end example - -Conceptually, tags are cumulative, i.e., they could only set a couple of -configuration variables, leaving others untouched. In practice, any tag -created with ltconfig will override all libtool configuration variables. -Only the two pre-defined tags, @samp{disable-shared} and -@samp{disable-static}, override a single variable, and can be used -cumulatively, after other tags. - -@emph{NOTE}: C++ support may be automatically added to your package by -adding the @code{AC_LIBTOOL_CXX} macro to your package -@file{configure.in} file. - -@node C++ libraries -@section Writing libraries for C++ -@c FIXME: in the TOC, the ++ is too large (seems to be math mode) -@cindex trouble with C++ -@cindex pitfalls using C++ -@cindex C++, pitfalls - -@emph{NOTE}: The problems described in this section may no longer -relevant due to the @samp{libtool} multi-language support. To enable -C++ support in libtool, use the @code{AC_LIBTOOL_CXX} macro in your -@file{configure.in} file. - -Creating libraries of C++ code should be a fairly straightforward -process, because its object files differ from C ones in only three ways: - -@enumerate 1 -@item -Because of name mangling, C++ libraries are only usable by the C++ -compiler that created them. This decision was made by the designers of -C++ in order to protect users from conflicting implementations of -features such as constructors, exception handling, and RTTI. - -@item -On some systems, the C++ compiler must take special actions for the -dynamic linker to run dynamic (i.e., run-time) initializers. This means -that we should not call @file{ld} directly to link such libraries, and -we should use the C++ compiler instead. - -@item -C++ compilers will link some Standard C++ library in by default, but -libtool does not know which are these libraries, so it cannot even run -the inter-library dependence analyzer to check how to link it in. -Therefore, running @file{ld} to link a C++ program or library is deemed -to fail. However, running the C++ compiler directly may lead to -problems related with inter-library dependencies. -@end enumerate - -The conclusion is that libtool is not ready for general use for C++ -libraries. You should avoid any global or static variable -initializations that would cause an ``initializer element is not -constant'' error if you compiled them with a standard C compiler. - -There are other ways of working around this problem, but they are beyond -the scope of this manual. - -Furthermore, you'd better find out, at configure time, what are the C++ -Standard libraries that the C++ compiler will link in by default, and -explicitly list them in the link command line. Hopefully, in the -future, libtool will be able to do this job by itself. - - -@node Troubleshooting -@chapter Troubleshooting -@cindex troubleshooting -@cindex problems, solving -@cindex solving problems -@cindex problems, blaming somebody else for - -Libtool is under constant development, changing to remain up-to-date -with modern operating systems. If libtool doesn't work the way you -think it should on your platform, you should read this chapter to help -determine what the problem is, and how to resolve it. - -@menu -* Libtool test suite:: Libtool's self-tests. -* Reporting bugs:: How to report problems with libtool. -@end menu - -@node Libtool test suite -@section The libtool test suite -@cindex test suite - -Libtool comes with its own set of programs that test its capabilities, -and report obvious bugs in the libtool program. These tests, too, are -constantly evolving, based on past problems with libtool, and known -deficiencies in other operating systems. - -As described in the @file{INSTALL} file, you may run @kbd{make check} -after you have built libtool (possibly before you install it) in order -to make sure that it meets basic functional requirements. - -@menu -* Test descriptions:: The contents of the test suite. -* When tests fail:: What to do when a test fails. -@end menu - -@node Test descriptions -@subsection Description of test suite - -Here is a list of the current programs in the test suite, and what they -test for: - -@table @file - -@item cdemo-conf.test -@itemx cdemo-exec.test -@itemx cdemo-make.test -@itemx cdemo-static.test -@itemx cdemo-shared.test -@pindex cdemo-conf.test -@pindex cdemo-exec.test -@pindex cdemo-make.test -@pindex cdemo-static.test -@pindex cdemo-shared.test -These programs check to see that the @file{cdemo} subdirectory of the -libtool distribution can be configured and built correctly. - -The @file{cdemo} subdirectory contains a demonstration of libtool -convenience libraries, a mechanism that allows build-time static -libraries to be created, in a way that their components can be later -linked into programs or other libraries, even shared ones. - -The tests @file{cdemo-make.test} and @file{cdemo-exec.test} are executed -three times, under three different libtool configurations: -@file{cdemo-conf.test} configures @file{cdemo/libtool} to build both -static and shared libraries (the default for platforms that support -both), @file{cdemo-static.test} builds only static libraries -(@samp{--disable-shared}), and @file{cdemo-shared.test} builds only -shared libraries (@samp{--disable-static}). - -@item demo-conf.test -@itemx demo-exec.test -@itemx demo-inst.test -@itemx demo-make.test -@itemx demo-unst.test -@itemx demo-static.test -@itemx demo-shared.test -@itemx demo-nofast.test -@itemx demo-pic.test -@itemx demo-nopic.test -@pindex demo-conf.test -@pindex demo-exec.test -@pindex demo-inst.test -@pindex demo-make.test -@pindex demo-unst.test -@pindex demo-static.test -@pindex demo-shared.test -@pindex demo-nofast.test -@pindex demo-pic.test -@pindex demo-nopic.test -These programs check to see that the @file{demo} subdirectory of the -libtool distribution can be configured, built, installed, and -uninstalled correctly. - -The @file{demo} subdirectory contains a demonstration of a trivial -package that uses libtool. The tests @file{demo-make.test}, -@file{demo-exec.test}, @file{demo-inst.test} and -@file{demo-unst.test} are executed four times, under four different -libtool configurations: @file{demo-conf.test} configures -@file{demo/libtool} to build both static and shared libraries, -@file{demo-static.test} builds only static libraries -(@samp{--disable-shared}), and @file{demo-shared.test} builds only -shared libraries (@samp{--disable-static}). -@file{demo-nofast.test} configures @file{demo/libtool} to -disable the fast-install mode (@samp{--enable-fast-install=no}). -@file{demo-pic.test} configures @file{demo/libtool} to -prefer building PIC code (@samp{--with-pic}), @file{demo-nopic.test} -to prefer non-PIC code (@samp{--without-pic}). - -@item deplibs.test -@pindex deplibs.test -Many systems cannot link static libraries into shared libraries. -libtool uses a @code{deplibs_check_method} to prevent such cases. -This tests checks whether libtool's @code{deplibs_check_method} -works properly. - -@item hardcode.test -@pindex hardcode.test -On all systems with shared libraries, the location of the library can be -encoded in executables that are linked against it @pxref{Linking -executables}. This test checks the conditions under which your system -linker hardcodes the library location, and guarantees that they -correspond to libtool's own notion of how your linker behaves. - -@item build-relink.test -@pindex build-relink.test -Checks whether variable @var{shlibpath_overrides_runpath} is properly -set. If the test fails and @var{VERBOSE} is set, it will indicate what -the variable should have been set to. - -@item noinst-link.test -@pindex noinst-link.test -Checks whether libtool will not try to link with a previously installed -version of a library when it should be linking with a just-built one. - -@item depdemo-conf.test -@itemx depdemo-exec.test -@itemx depdemo-inst.test -@itemx depdemo-make.test -@itemx depdemo-unst.test -@itemx depdemo-static.test -@itemx depdemo-shared.test -@itemx depdemo-nofast.test -@pindex depdemo-conf.test -@pindex depdemo-exec.test -@pindex depdemo-inst.test -@pindex depdemo-make.test -@pindex depdemo-unst.test -@pindex depdemo-static.test -@pindex depdemo-shared.test -@pindex depdemo-nofast.test -These programs check to see that the @file{depdemo} subdirectory of the -libtool distribution can be configured, built, installed, and -uninstalled correctly. - -The @file{depdemo} subdirectory contains a demonstration of inter-library -dependencies with libtool. The test programs link some interdependent -libraries. - -The tests @file{depdemo-make.test}, @file{depdemo-exec.test}, -@file{depdemo-inst.test} and @file{depdemo-unst.test} are executed -four times, under four different libtool configurations: -@file{depdemo-conf.test} configures @file{depdemo/libtool} to build both -static and shared libraries, @file{depdemo-static.test} builds only static -libraries (@samp{--disable-shared}), and @file{depdemo-shared.test} builds -only shared libraries (@samp{--disable-static}). -@file{depdemo-nofast.test} configures @file{depdemo/libtool} to -disable the fast-install mode (@samp{--enable-fast-install=no}. - -@item mdemo-conf.test -@itemx mdemo-exec.test -@itemx mdemo-inst.test -@itemx mdemo-make.test -@itemx mdemo-unst.test -@itemx mdemo-static.test -@itemx mdemo-shared.test -@pindex mdemo-conf.test -@pindex mdemo-exec.test -@pindex mdemo-inst.test -@pindex mdemo-make.test -@pindex mdemo-unst.test -@pindex mdemo-static.test -@pindex mdemo-shared.test -These programs check to see that the @file{mdemo} subdirectory of the -libtool distribution can be configured, built, installed, and -uninstalled correctly. - -The @file{mdemo} subdirectory contains a demonstration of a package that -uses libtool and the system independent dlopen wrapper @file{libltdl} to -load modules. The library @file{libltdl} provides a dlopen wrapper for -various platforms (Linux, Solaris, HP/UX etc.) including support for -dlpreopened modules (@pxref{Dlpreopening}). - -The tests @file{mdemo-make.test}, @file{mdemo-exec.test}, -@file{mdemo-inst.test} and @file{mdemo-unst.test} are executed -three times, under three different libtool configurations: -@file{mdemo-conf.test} configures @file{mdemo/libtool} to build both -static and shared libraries, @file{mdemo-static.test} builds only static -libraries (@samp{--disable-shared}), and @file{mdemo-shared.test} builds -only shared libraries (@samp{--disable-static}). - -@item tagdemo-conf.test -@itemx tagdemo-exec.test -@itemx tagdemo-make.test -@itemx tagdemo-static.test -@itemx tagdemo-shared.test -@pindex tagdemo-conf.test -@pindex tagdemo-exec.test -@pindex tagdemo-make.test -@pindex tagdemo-static.test -@pindex tagdemo-shared.test -These programs check to see that the @file{tagdemo} subdirectory of the -libtool distribution can be configured and built correctly. - -The @file{tagdemo} subdirectory contains a demonstration of a package -that uses libtool and its tagged configuration support -(@pxref{Configuration tags}) build a C++ library. C++ shared library -support is enabled by using the @code{AC_LIBTOOL_CXX} macro in -@file{tagdemo/configure.in}. - -The tests @file{tagdemo-make.test}, and @file{tagdemo-exec.test}, are -executed three times, under three different libtool configurations: -@file{tagdemo-conf.test} configures @file{tagdemo/libtool} to build both -static and shared libraries, @file{tagdemo-static.test} builds only -static libraries (@samp{--disable-shared}), and -@file{tagdemo-shared.test} builds only shared libraries -(@samp{--disable-static}). - -@item dryrun.test -@pindex dryrun.test -This test checks whether libtool's @code{--dry-run} mode works properly. - -@item assign.test -@pindex assign.test -Checks whether we don't put break or continue on the same -line as an assignment in the libtool script. - -@item link.test -@pindex link.test -This test guarantees that linking directly against a non-libtool static -library works properly. - -@item link-2.test -@pindex link-2.test -This test makes sure that files ending in @samp{.lo} are never linked -directly into a program file. - -@item nomode.test -@pindex nomode.test -Check whether we can actually get help for libtool. - -@item quote.test -@pindex quote.test -This program checks libtool's metacharacter quoting. - -@item sh.test -@pindex sh.test -Checks whether a `test' command was forgotten in libtool. - -@item suffix.test -@pindex suffix.test -When other programming languages are used with libtool (@pxref{Other -languages}), the source files may end in suffixes other than @samp{.c}. -This test validates that libtool can handle suffixes for all the file -types that it supports, and that it fails when the suffix is invalid. - -@end table - -@node When tests fail -@subsection When tests fail -@cindex failed tests -@cindex tests, failed - -Each of the above tests are designed to produce no output when they are -run via @kbd{make check}. The exit status of each program tells the -@file{Makefile} whether or not the test succeeded. - -If a test fails, it means that there is either a programming error in -libtool, or in the test program itself. - -To investigate a particular test, you may run it directly, as you would -a normal program. When the test is invoked in this way, it produces -output which may be useful in determining what the problem is. - -Another way to have the test programs produce output is to set the -@var{VERBOSE} environment variable to @samp{yes} before running them. -For example, @kbd{env VERBOSE=yes make check} runs all the tests, and -has each of them display debugging information. - -@node Reporting bugs -@section Reporting bugs -@cindex bug reports -@cindex reporting bugs -@cindex problem reports - -If you think you have discovered a bug in libtool, you should think -twice: the libtool maintainer is notorious for passing the buck (or -maybe that should be ``passing the bug''). Libtool was invented to fix -known deficiencies in shared library implementations, so, in a way, most -of the bugs in libtool are actually bugs in other operating systems. -However, the libtool maintainer would definitely be happy to add support -for somebody else's buggy operating system. [I wish there was a good -way to do winking smiley-faces in Texinfo.] - -Genuine bugs in libtool include problems with shell script portability, -documentation errors, and failures in the test suite (@pxref{Libtool -test suite}). - -First, check the documentation and help screens to make sure that the -behaviour you think is a problem is not already mentioned as a feature. - -Then, you should read the Emacs guide to reporting bugs (@pxref{Bugs, , -Reporting Bugs, emacs, The Emacs Manual}). Some of the details -listed there are specific to Emacs, but the principle behind them is a -general one. - -Finally, send a bug report to @value{BUGADDR} with any appropriate -@emph{facts}, such as test suite output (@pxref{When tests fail}), all -the details needed to reproduce the bug, and a brief description of why -you think the behaviour is a bug. Be sure to include the word -``libtool'' in the subject line, as well as the version number you are -using (which can be found by typing @kbd{ltconfig --version}). - -@node Maintaining -@chapter Maintenance notes for libtool - -This chapter contains information that the libtool maintainer finds -important. It will be of no use to you unless you are considering -porting libtool to new systems, or writing your own libtool. - -@menu -* New ports:: How to port libtool to new systems. -* Tested platforms:: When libtool was last tested. -* Platform quirks:: Information about different library systems. -* libtool script contents:: Configuration information that libtool uses. -* Cheap tricks:: Making libtool maintainership easier. -@end menu - -@node New ports -@section Porting libtool to new systems - -Before you embark on porting libtool to an unsupported system, it is -worthwhile to send e-mail to @value{MAILLIST}, to make sure that you are -not duplicating existing work. - -If you find that any porting documentation is missing, please complain! -Complaints with patches and improvements to the documentation, or to -libtool itself, are more than welcome. - -@menu -* Information sources:: Where to find relevant documentation -* Porting inter-library dependencies:: Implementation details explained -@end menu - -@node Information sources -@subsection Information sources - -Once it is clear that a new port is necessary, you'll generally need the -following information: - -@table @asis -@item canonical system name -You need the output of @code{config.guess} for this system, so that you -can make changes to the libtool configuration process without affecting -other systems. - -@item man pages for @code{ld} and @code{cc} -These generally describe what flags are used to generate PIC, to create -shared libraries, and to link against only static libraries. You may -need to follow some cross references to find the information that is -required. - -@item man pages for @code{ld.so}, @code{rtld}, or equivalent -These are a valuable resource for understanding how shared libraries are -loaded on the system. - -@item man page for @code{ldconfig}, or equivalent -This page usually describes how to install shared libraries. - -@item output from @kbd{ls -l /lib /usr/lib} -This shows the naming convention for shared libraries on the system, -including which names should be symbolic links. - -@item any additional documentation -Some systems have special documentation on how to build and install -shared libraries. -@end table - -If you know how to program the Bourne shell, then you can complete the -port yourself; otherwise, you'll have to find somebody with the relevant -skills who will do the work. People on the libtool mailing list are -usually willing to volunteer to help you with new ports, so you can send -the information to them. - -To do the port yourself, you'll definitely need to modify the -@code{ltconfig} script in order to make platform-specific changes to the -configuration process. You should search the script for the -@code{PORTME} keyword, which will give you some hints on what you'll -need to change. In general, all that is involved is modifying the -appropriate configuration variables (@pxref{libtool script contents}). - -Your best bet is to find an already-supported system that is similar to -yours, and make your changes based on that. In some cases, however, -your system will differ significantly from every other supported system, -and it may be necessary to add new configuration variables, and modify -the @code{ltmain.sh} script accordingly. Be sure to write to the -mailing list before you make changes to @code{ltmain.sh}, since they may -have advice on the most effective way of accomplishing what you want. - -@node Porting inter-library dependencies -@subsection Porting inter-library dependencies support -@cindex inter-library dependency -@vindex deplibs_check_method - -Since version 1.2c, libtool has re-introduced the ability to do -inter-library dependency on some platforms, thanks to a patch by Toshio -Kuratomi @email{badger@@prtr-13.ucsc.edu}. Here's a shortened version -of the message that contained his patch: - -The basic architecture is this: in @file{ltconfig.in}, the person who -writes libtool makes sure @samp{$deplibs} is included in -@samp{$archive_cmds} somewhere and also sets the variable -@samp{$deplibs_check_method}, and maybe @samp{$file_magic_cmd} when -@samp{deplibs_check_method} is file_magic. - -@samp{deplibs_check_method} can be one of five things: -@table @samp -@item file_magic [@var{regex}] -@vindex file_magic -@vindex file_magic_cmd -@vindex file_magic_test_file -looks in the library link path for libraries that have the right -libname. Then it runs @samp{$file_magic_cmd} on the library and checks -for a match against @samp{regex} using @code{egrep}. When -@var{file_magic_test_file} is set in @file{ltconfig}, it is used as an -argument to @samp{$file_magic_cmd} in order to verify whether the -regular expression matches its output, and warn the user otherwise. - -@item test_compile -@vindex test_compile -just checks whether it is possible to link a program out of a list of -libraries, and checks which of those are listed in the output of -@code{ldd}. It is currently unused, and will probably be dropped in the -future. - -@item pass_all -@vindex pass_all -will pass everything without any checking. This may work on platforms -in which code is position-independent by default and inter-library -dependencies are properly supported by the dynamic linker, for example, -on DEC OSF/1 3 and 4. - -@item none -@vindex none -It causes deplibs to be reassigned deplibs="". That way -@samp{archive_cmds} can contain deplibs on all platforms, but not have -deplibs used unless needed. - -@item unknown -@vindex unknown -is the default for all systems unless overridden in @file{ltconfig.in}. -It is the same as @samp{none}, but it documents that we really don't -know what the correct value should be, and we welcome patches that -improve it. -@end table - -Then in @file{ltmain.in} we have the real workhorse: a little -initialization and postprocessing (to setup/release variables for use -with eval echo libname_spec etc.) and a case statement that decides -which method is being used. This is the real code... I wish I could -condense it a little more, but I don't think I can without function -calls. I've mostly optimized it (moved things out of loops, etc) but -there is probably some fat left. I thought I should stop while I was -ahead, work on whatever bugs you discover, etc before thinking about -more than obvious optimizations. - -@node Tested platforms -@section Tested platforms - -This table describes when libtool was last known to be tested on -platforms where it claims to support shared libraries: - -@example -@include PLATFORMS -@end example - -Note: The vendor-distributed HP-UX @code{sed}(1) programs are horribly -broken, and cannot handle libtool's requirements, so users may report -unusual problems. There is no workaround except to install a working -@code{sed} (such as GNU @code{sed}) on these systems. - -Note: The vendor-distributed NCR MP-RAS @code{cc} programs emits -copyright on standard error that confuse tests on size of -@file{conftest.err}. The workaround is to specify @code{CC} -when run @code{configure} with @kbd{CC='cc -Hnocopyr'}. - -@node Platform quirks -@section Platform quirks - -This section is dedicated to the sanity of the libtool maintainers. It -describes the programs that libtool uses, how they vary from system to -system, and how to test for them. - -Because libtool is a shell script, it can be difficult to understand -just by reading it from top to bottom. This section helps show why -libtool does things a certain way. Combined with the scripts -themselves, you should have a better sense of how to improve libtool, or -write your own. - -@menu -* References:: Finding more information. -* Compilers:: Creating object files from source files. -* Reloadable objects:: Binding object files together. -* Archivers:: Programs that create static archives. -@end menu - -@node References -@subsection References - -The following is a list of valuable documentation references: - -@itemize @bullet -@item -SGI's IRIX Manual Pages, which can be found at -@url{http://techpubs.sgi.com/cgi-bin/infosrch.cgi?cmd=browse&db=man}. - -@item -Sun's free service area -(@url{http://www.sun.com/service/online/free.html}) and documentation -server (@url{http://docs.sun.com/}). -@end itemize - -@node Compilers -@subsection Compilers - -The only compiler characteristics that affect libtool are the flags -needed (if any) to generate PIC objects. In general, if a C compiler -supports certain PIC flags, then any derivative compilers support the -same flags. Until there are some noteworthy exceptions to this rule, -this section will document only C compilers. - -The following C compilers have standard command line options, regardless -of the platform: - -@table @code -@item gcc - -This is the GNU C compiler, which is also the system compiler for many -free operating systems (FreeBSD, GNU/Hurd, GNU/Linux, Lites, NetBSD, and -OpenBSD, to name a few). - -The @samp{-fpic} or @samp{-fPIC} flags can be used to generate -position-independent code. @samp{-fPIC} is guaranteed to generate -working code, but the code is slower on m68k, m88k, and Sparc chips. -However, using @samp{-fpic} on those chips imposes arbitrary size limits -on the shared libraries. -@end table - -The rest of this subsection lists compilers by the operating system that -they are bundled with: - -@c FIXME these should all be better-documented - -@table @code -@item aix3* -@itemx aix4* -AIX compilers have no PIC flags, since AIX has been ported only to -PowerPC and RS/6000 chips. @footnote{All code compiled for the PowerPC -and RS/6000 chips (@code{powerpc-*-*}, @code{powerpcle-*-*}, and -@code{rs6000-*-*}) is position-independent, regardless of the operating -system or compiler suite. So, ``regular objects'' can be used to build -shared libraries on these systems and no special PIC compiler flags are -required.} - -@item hpux10* -Use @samp{+Z} to generate PIC. - -@item osf3* -Digital/UNIX 3.x does not have PIC flags, at least not on the PowerPC -platform. - -@item solaris2* -Use @samp{-KPIC} to generate PIC. - -@item sunos4* -Use @samp{-PIC} to generate PIC. -@end table - -@node Reloadable objects -@subsection Reloadable objects - -On all known systems, a reloadable object can be created by running -@kbd{ld -r -o @var{output}.o @var{input1}.o @var{input2}.o}. This -reloadable object may be treated as exactly equivalent to other -objects. - -@node Archivers -@subsection Archivers - -On all known systems, building a static library can be accomplished by -running @kbd{ar cru lib@var{name}.a @var{obj1}.o @var{obj2}.o @dots{}}, -where the @samp{.a} file is the output library, and each @samp{.o} file is an -object file. - -On all known systems, if there is a program named @code{ranlib}, then it -must be used to ``bless'' the created library before linking against it, -with the @kbd{ranlib lib@var{name}.a} command. Some systems, like Irix, -use the @code{ar ts} command, instead. - -@node libtool script contents -@section @code{libtool} script contents -@cindex implementation of libtool -@cindex libtool implementation - -The @code{libtool} script is generated by @code{ltconfig} -(@pxref{Configuring}). From libtool version 0.7 to 1.0, this script -simply set shell variables, then sourced the libtool backend, -@code{ltmain.sh}. @code{ltconfig} from libtool version 1.1 and later -inlines the contents of @code{ltmain.sh} into the generated -@code{libtool}, which improves performance on many systems. - -The convention used for naming variables which hold shell commands for -delayed evaluation, is to use the suffix @code{_cmd} where a single -line of valid shell script is needed, and the suffix @code{_cmds} where -multiple lines of shell script @strong{may} be delayed for later -evaluation. By convention, @code{_cmds} variables delimit the -evaluation units with the @code{~} character where necessary. - -Here is a listing of each of the configuration variables, and how they -are used within @code{ltmain.sh}: - -@defvar AR -The name of the system library archiver. -@end defvar - -@defvar CC -The name of the C compiler used to configure libtool. -@end defvar - -@defvar LD -The name of the linker that libtool should use internally for reloadable -linking and possibly shared libraries. -@end defvar - -@defvar LTCONFIG_VERSION -This is set to the version number of the @code{ltconfig} script, to -prevent mismatches between the configuration information in -@code{libtool}, and how that information is used in @code{ltmain.sh}. -@end defvar - -@defvar NM -The name of a BSD-compatible @code{nm} program, which produces listings -of global symbols in one the following formats: - -@example -@var{address} C @var{global-variable-name} -@var{address} D @var{global-variable-name} -@var{address} T @var{global-function-name} -@end example -@end defvar - -@defvar RANLIB -Set to the name of the ranlib program, if any. -@end defvar - -@defvar allow_undefined_flag -The flag that is used by @samp{archive_cmds} in order to declare that -there will be unresolved symbols in the resulting shared library. -Empty, if no such flag is required. Set to @samp{unsupported} if there -is no way to generate a shared library with references to symbols that -aren't defined in that library. -@end defvar - -@defvar always_export_symbols -Whether libtool should automatically generate a list of exported symbols -using @var{export_symbols_cmds} before linking an archive. -Set to @samp{yes} or @samp{no}. Default is @samp{no}. -@end defvar - -@defvar archive_cmds -@defvarx archive_expsym_cmds -@defvarx old_archive_cmds -Commands used to create shared libraries, shared libraries with -@samp{-export-symbols} and static libraries, respectively. -@end defvar - -@defvar old_archive_from_new_cmds -If the shared library depends on a static library, -@samp{old_archive_from_new_cmds} contains the commands used to create that -static library. If this variable is not empty, @samp{old_archive_cmds} is -not used. -@end defvar - -@defvar old_archive_from_expsyms_cmds -If a static library must be created from the export symbol list in order to -correctly link with a shared library, @samp{old_archive_from_expsyms_cmds} -contains the commands needed to create that static library. When these -commands are executed, the variable @var{soname} contains the name of the -shared library in question, and the @var{$objdir/$newlib} contains the -path of the static library these commands should build. After executing -these commands, libtool will proceed to link against @var{$objdir/$newlib} -instead of @var{soname}. -@end defvar - -@defvar build_libtool_libs -Whether libtool should build shared libraries on this system. Set to -@samp{yes} or @samp{no}. -@end defvar - -@defvar build_old_libs -Whether libtool should build static libraries on this system. Set to -@samp{yes} or @samp{no}. -@end defvar - -@defvar compiler_c_o -Whether the compiler supports the @code{-c} and @code{-o} options -simultaneously. Set to @samp{yes} or @samp{no}. -@end defvar - -@defvar compiler_o_lo -Whether the compiler supports compiling directly to a ".lo" file, -i.e whether object files do not have to have the suffix ".o". -Set to @samp{yes} or @samp{no}. -@end defvar - -@defvar dlopen_support -Whether @code{dlopen} is supported on the platform. -Set to @samp{yes} or @samp{no}. -@end defvar - -@defvar dlopen_self -Whether it is possible to @code{dlopen} the executable itself. -Set to @samp{yes} or @samp{no}. -@end defvar - -@defvar dlopen_self_static -Whether it is possible to @code{dlopen} the executable itself, when it -is linked statically (@samp{-all-static}). Set to @samp{yes} or -@samp{no}. -@end defvar - -@defvar echo -An @code{echo} program which does not interpret backslashes as an -escape character. -@end defvar - -@defvar exclude_expsyms -List of symbols that should not be listed in the preloaded symbols. -@end defvar - -@defvar export_dynamic_flag_spec -Compiler link flag that allows a dlopened shared library to reference -symbols that are defined in the program. -@end defvar - -@defvar export_symbols_cmds -Commands to extract exported symbols from @var{libobjs} to the -file @var{export_symbols}. -@end defvar - -@defvar extract_expsyms_cmds -Commands to extract the exported symbols list from a shared library. -These commands are executed if there is no file @var{$objdir/$soname-def}, -and should write the names of the exported symbols to that file, for -the use of @samp{old_archive_from_expsyms_cmds}. -@end defvar - -@defvar fast_install -Determines whether libtool will privilege the installer or the -developer. The assumption is that installers will seldom run programs -in the build tree, and the developer will seldom install. This is only -meaningful on platforms in which @var{shlibpath_overrides_runpath} is -not @samp{yes}, so @var{fast_install} will be set to @samp{needless} in -this case. If @var{fast_install} set to @samp{yes}, libtool will create -programs that search for installed libraries, and, if a program is run -in the build tree, a new copy will be linked on-demand to use the -yet-to-be-installed libraries. If set to @samp{no}, libtool will create -programs that use the yet-to-be-installed libraries, and will link -a new copy of the program at install time. The default value is -@samp{yes} or @samp{needless}, depending on platform and configuration -flags, and it can be turned from @samp{yes} to @samp{no} with the -configure flag @samp{--disable-fast-install}. -@end defvar - -@defvar finish_cmds -Commands to tell the dynamic linker how to find shared libraries in a -specific directory. -@end defvar - -@defvar finish_eval -Same as @var{finish_cmds}, except the commands are not displayed. -@end defvar - -@defvar fix_srcfile_path -Expression to fix the shell variable $srcfile for the compiler. -@end defvar - -@defvar global_symbol_pipe -A pipeline that takes the output of @var{NM}, and produces a listing of -raw symbols followed by their C names. For example: - -@example -$ @kbd{eval "$NM progname | $global_symbol_pipe"} -D @var{symbol1} @var{C-symbol1} -T @var{symbol2} @var{C-symbol2} -C @var{symbol3} @var{C-symbol3} -@dots{} -$ -@end example - -The first column contains the symbol type (used to tell data from code -on some platforms), but its meaning is system dependent. -@end defvar - -@defvar global_symbol_to_cdecl -A pipeline that translates the output of @var{global_symbol_pipe} into -proper C declarations. On platforms whose linkers differentiate code -from data, such as HP/UX, data symbols will be declared as such, and -code symbols will be declared as functions. On platforms that don't -care, everything is assumed to be data. -@end defvar - -@defvar hardcode_action -Either @samp{immediate} or @samp{relink}, depending on whether shared -library paths can be hardcoded into executables before they are installed, -or if they need to be relinked. -@end defvar - -@defvar hardcode_direct -Set to @samp{yes} or @samp{no}, depending on whether the linker -hardcodes directories if a library is directly specified on the command -line (such as @samp{@var{dir}/lib@var{name}.a}) when -@var{hardcode_libdir_flag_spec} is specified. -@end defvar - -@defvar hardcode_into_libs -Whether the platform supports hardcoding of run-paths into libraries. -If enabled, linking of programs will be much simpler but libraries will -need to be relinked during installation. Set to @samp{yes} or @samp{no}. -@end defvar - -@defvar hardcode_libdir_flag_spec -Flag to hardcode a @var{libdir} variable into a binary, so that the -dynamic linker searches @var{libdir} for shared libraries at runtime. -If it is empty, libtool will try to use some other hardcoding mechanism. -@end defvar - -@defvar hardcode_libdir_separator -If the compiler only accepts a single @var{hardcode_libdir_flag}, then -this variable contains the string that should separate multiple -arguments to that flag. -@end defvar - -@defvar hardcode_minus_L -Set to @samp{yes} or @samp{no}, depending on whether the linker -hardcodes directories specified by @samp{-L} flags into the resulting -executable when @var{hardcode_libdir_flag_spec} is specified. -@end defvar - -@defvar hardcode_shlibpath_var -Set to @samp{yes} or @samp{no}, depending on whether the linker -hardcodes directories by writing the contents of @samp{$shlibpath_var} -into the resulting executable when @var{hardcode_libdir_flag_spec} is -specified. Set to @samp{unsupported} if directories specified by -@samp{$shlibpath_var} are searched at run time, but not at link time. -@end defvar - -@defvar host -@defvarx host_alias -For information purposes, set to the specified and canonical names of -the system that libtool was configured for. -@end defvar - -@defvar include_expsyms -List of symbols that must always be exported when using @var{export_symbols}. -@end defvar - -@defvar libext -The standard old archive suffix (normally "a"). -@end defvar - -@defvar libname_spec -The format of a library name prefix. On all Unix systems, static -libraries are called @samp{lib@var{name}.a}, but on some systems (such -as OS/2 or MS-DOS), the library is just called @samp{@var{name}.a}. -@end defvar - -@defvar library_names_spec -A list of shared library names. The first is the name of the file, -the rest are symbolic links to the file. The name in the list is -the file name that the linker finds when given @samp{-l@var{name}}. -@end defvar - -@defvar link_all_deplibs -Whether libtool must link a program against all its dependency libraries. -Set to @samp{yes} or @samp{no}. Default is @samp{unknown}, which is -a synonym for @samp{yes}. -@end defvar - -@defvar link_static_flag -Linker flag (passed through the C compiler) used to prevent dynamic -linking. -@end defvar - -@defvar need_lib_prefix -Whether libtool should automatically prefix module names with 'lib'. -Set to @samp{yes} or @samp{no}. By default, it is @samp{unknown}, which -means the same as @samp{yes}, but documents that we are not really sure -about it. -@samp{yes} means that it is possible both to @code{dlopen} and to -link against a library without 'lib' prefix, -i.e. it requires @var{hardcode_direct} to be @samp{yes}. -@end defvar - -@defvar need_version -Whether versioning is required for libraries, i.e. whether the -dynamic linker requires a version suffix for all libraries. -Set to @samp{yes} or @samp{no}. By default, it is @samp{unknown}, which -means the same as @samp{yes}, but documents that we are not really sure -about it. -@end defvar - -@defvar need_locks -Whether files must be locked to prevent conflicts when compiling -simultaneously. Set to @samp{yes} or @samp{no}. -@end defvar - -@defvar no_builtin_flag -Compiler flag to disable builtin functions that conflict with declaring -external global symbols as @code{char}. -@end defvar - -@defvar no_undefined_flag -The flag that is used by @samp{archive_cmds} in order to declare that -there will be no unresolved symbols in the resulting shared library. -Empty, if no such flag is required. -@end defvar - -@defvar objdir -The name of the directory that contains temporary libtool files. -@end defvar - -@defvar objext -The standard object file suffix (normally "o"). -@end defvar - -@defvar pic_flag -Any additional compiler flags for building library object files. -@end defvar - -@defvar postinstall_cmds -@defvarx old_postinstall_cmds -Commands run after installing a shared or static library, respectively. -@end defvar - -@defvar postuninstall_cmds -@defvarx old_postuninstall_cmds -Commands run after uninstalling a shared or static library, respectively. -@end defvar - -@defvar reload_cmds -@defvarx reload_flag -Commands to create a reloadable object. -@end defvar - -@defvar runpath_var -The environment variable that tells the linker which directories to -hardcode in the resulting executable. -@end defvar - -@defvar shlibpath_overrides_runpath -Indicates whether it is possible to override the hard-coded library -search path of a program with an environment variable. If this is set -to no, libtool may have to create two copies of a program in the build -tree, one to be installed and one to be run in the build tree only. -When each of these copies is created depends on the value of -@code{fast_install}. The default value is @samp{unknown}, which is -equivalent to @samp{no}. -@end defvar - -@defvar shlibpath_var -The environment variable that tells the dynamic linker where to find -shared libraries. -@end defvar - -@defvar soname_spec -The name coded into shared libraries, if different from the real name of -the file. -@end defvar - -@defvar striplib -@defvarx old_striplib -Command to strip a shared (@code{striplib}) or static (@code{old_striplib}) -library, respectively. If these variables are empty, the strip flag -in the install mode will be ignored for libraries (@pxref{Install mode}). -@end defvar - -@defvar sys_lib_dlsearch_path_spec -Expression to get the run-time system library search path. Directories -that appear in this list are never hard-coded into executables. -@end defvar - -@defvar sys_lib_search_path_spec -Expression to get the compile-time system library search path. This -variable is used by libtool when it has to test whether a certain -library is shared or static. The directories listed in -@var{shlibpath_var} are automatically appended to this list, every time -libtool runs (i.e., not at configuration time), because some linkers use -this variable to extend the library search path. Linker switches such -as @code{-L} also augment the search path. -@end defvar - -@defvar thread_safe_flag_spec -Linker flag (passed through the C compiler) used to generate thread-safe -libraries. -@end defvar - -@defvar version_type -The library version numbering type. One of @samp{libtool}, -@samp{linux}, @samp{osf}, @samp{sunos}, or @samp{none}. -@end defvar - -@defvar whole_archive_flag_spec -Compiler flag to generate shared objects from convenience archives. -@end defvar - -@defvar wl -The C compiler flag that allows libtool to pass a flag directly to the -linker. Used as: @code{$@{wl@}@var{some-flag}}. -@end defvar - -Variables ending in @samp{_cmds} or @samp{_eval} contain a -semicolon-separated list of commands that are @code{eval}ed one after -another. If any of the commands return a nonzero exit status, libtool -generally exits with an error message. - -Variables ending in @samp{_spec} are @code{eval}ed before being used by -libtool. - -@node Cheap tricks -@section Cheap tricks - -Here are a few tricks that you can use in order to make maintainership -easier: - -@itemize @bullet -@item -When people report bugs, ask them to use the @samp{--config}, -@samp{--debug}, or @samp{--features} flags, if you think they will help -you. These flags are there to help you get information directly, rather -than having to trust second-hand observation. - -@item -Rather than reconfiguring libtool every time I make a change to -@code{ltconfig.in} or @code{ltmain.in}, I keep a permanent -@code{libtool} script in my @var{PATH}, which sources @code{ltmain.in} -directly. - -The following steps describe how to create such a script, where -@code{/home/src/libtool} is the directory containing the libtool source -tree, @code{/home/src/libtool/libtool} is a libtool script that has been -configured for your platform, and @code{~/bin} is a directory in your -@var{PATH}: - -@example -trick$ @kbd{cd ~/bin} -trick$ @kbd{sed '/^# ltmain\.sh/q' /home/src/libtool/libtool > libtool} -trick$ @kbd{cat >> libtool -LTCONFIG_VERSION="@@VERSION@@" -. /home/src/libtool/ltmain.in -^D} -trick$ @kbd{chmod +x libtool} -trick$ @kbd{libtool --version} -ltmain.sh (GNU @@PACKAGE@@) @@VERSION@@ -trick$ -@end example -@end itemize - -The output of the final @samp{libtool --version} command shows that the -@code{ltmain.in} script is being used directly. Now, modify -@code{~/bin/libtool} or @code{/home/src/libtool/ltmain.in} directly in -order to test new changes without having to rerun @code{ltconfig}. - -@page -@node Index -@unnumbered Index - -@printindex cp - -@c summarycontents -@contents -@bye +As a rule of thumb, link a libtool convenience library into at most one +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 +@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 + +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