From a4460f6d9453bbd7e584937686449cef3e19f052 Mon Sep 17 00:00:00 2001 From: Leo Tenenbaum Date: Mon, 20 Aug 2018 20:34:57 -0400 Subject: Initial commit --- gtk+-mingw/share/info/libtool.info-1 | 6698 ++++++++++++++++++++++++++++++++++ 1 file changed, 6698 insertions(+) create mode 100644 gtk+-mingw/share/info/libtool.info-1 (limited to 'gtk+-mingw/share/info/libtool.info-1') diff --git a/gtk+-mingw/share/info/libtool.info-1 b/gtk+-mingw/share/info/libtool.info-1 new file mode 100644 index 0000000..6d16648 --- /dev/null +++ b/gtk+-mingw/share/info/libtool.info-1 @@ -0,0 +1,6698 @@ +This is doc/libtool.info, produced by makeinfo version 4.13 from +./doc/libtool.texi. + +INFO-DIR-SECTION GNU programming tools +START-INFO-DIR-ENTRY +* Libtool: (libtool). Generic shared library support script. +END-INFO-DIR-ENTRY + +INFO-DIR-SECTION Individual utilities +START-INFO-DIR-ENTRY +* libtool-invocation: (libtool)Invoking libtool. + Running the `libtool' script. +* libtoolize: (libtool)Invoking libtoolize. Adding libtool support. +END-INFO-DIR-ENTRY + + This file documents GNU Libtool 2.4.2 + + Copyright (C) 1996-2011 Free Software Foundation, Inc. + + Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with no +Invariant Sections, with no Front-Cover Texts, and with no Back-Cover +Texts. A copy of the license is included in the section entitled "GNU +Free Documentation License". + + +File: libtool.info, Node: Top, Next: Introduction, Prev: (dir), Up: (dir) + +Shared library support for GNU +****************************** + +This file documents GNU Libtool, a script that allows package developers +to provide generic shared library support. This edition documents +version 2.4.2. + + *Note Reporting bugs::, for information on how to report problems +with GNU Libtool. + +* Menu: + +* Introduction:: What the heck is libtool? +* Libtool paradigm:: How libtool's view of libraries is different. +* Using libtool:: Example of using libtool to build libraries. +* Invoking libtool:: Running the `libtool' script. +* Integrating libtool:: Using libtool in your own packages. +* Other languages:: Using libtool without a C compiler. +* Versioning:: Using library interface versions. +* Library tips:: Tips for library interface design. +* Inter-library dependencies:: Libraries that depend on other libraries. +* Dlopened modules:: `dlopen'ing libtool-created libraries. +* Using libltdl:: Libtool's portable `dlopen' wrapper library. +* Trace interface:: Libtool's trace interface. +* FAQ:: Frequently Asked Questions +* Troubleshooting:: When libtool doesn't work as advertised. +* Maintaining:: Information used by the libtool maintainer. +* GNU Free Documentation License:: License for this manual. +* Combined Index:: Full index. + + --- 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. + +Linking executables + +* Wrapper executables:: Wrapper executables for some platforms. + +Invoking `libtool' + +* Compile mode:: Creating library object files. +* Link mode:: Generating executables and libraries. +* Execute mode:: Debugging libtool-generated programs. +* Install mode:: Making libraries and executables public. +* Finish mode:: Completing a library installation. +* Uninstall mode:: Removing installed executables and libraries. +* Clean mode:: Removing uninstalled executables and libraries. + +Integrating libtool with your package + +* Autoconf macros:: Autoconf macros exported by libtool. +* Makefile rules:: Writing `Makefile' rules for libtool. +* Using Automake:: Automatically supporting libtool. +* Configuring:: Configuring libtool for a host system. +* Distributing:: What files to distribute with your package. +* Static-only libraries:: Sometimes shared libraries are just a pain. + +Configuring libtool + +* LT_INIT:: Configuring `libtool' in `configure.ac'. +* Configure notes:: Platform-specific notes for configuration. + +Including libtool in your package + +* Invoking libtoolize:: `libtoolize' command line options. +* Autoconf and LTLIBOBJS:: Autoconf automates LTLIBOBJS generation. + +Using libtool with other languages + +* C++ libraries:: Writing libraries for C++ +* Tags:: Tags + +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. +* Linking with dlopened modules:: Using dlopenable modules in libraries. +* Finding the dlname:: Choosing the right file to `dlopen'. +* Dlopen issues:: Unresolved problems that need your attention. + +Using libltdl + +* Libltdl interface:: How to use libltdl in your programs. +* Modules for libltdl:: Creating modules that can be `dlopen'ed. +* Thread Safety in libltdl:: Registering callbacks for multi-thread safety. +* User defined module data:: Associating data with loaded modules. +* Module loaders for libltdl:: Creating user defined module loaders. +* Distributing libltdl:: How to distribute libltdl with your package. + +Frequently Asked Questions about libtool + +* Stripped link flags:: Dropped flags when creating a library + +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 old 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. +* Multiple dependencies:: Removing duplicate dependent libraries. +* Archivers:: Programs that create static archives. +* Cross compiling:: Issues that arise when cross compiling. +* File name conversion:: Converting file names between platforms. +* Windows DLLs:: Windows header defines. + +File name conversion + +* File Name Conversion Failure:: What happens when file name conversion fails +* Native MinGW File Name Conversion:: MSYS file name conversion idiosyncrasies +* Cygwin/Windows File Name Conversion:: Using `cygpath' to convert Cygwin file names +* Unix/Windows File Name Conversion:: Using Wine to convert Unix paths +* LT_CYGPATH:: Invoking `cygpath' from other environments +* Cygwin to MinGW Cross:: Other notes concerning MinGW cross + + +File: libtool.info, Node: Introduction, Next: Libtool paradigm, Prev: Top, Up: Top + +1 Introduction +************** + +In the past, if you were a source code package developer and wanted to +take advantage of the power of shared libraries, you needed to write +custom support code for each platform on which your package ran. You +also had to design a configuration interface so that the package +installer could choose what sort of libraries were built. + + GNU Libtool simplifies your job by encapsulating both the +platform-specific dependencies, and the user interface, in a single +script. GNU Libtool is designed so that the complete functionality of +each host type is available via a generic interface, but nasty quirks +are hidden from the programmer. + + GNU Libtool's consistent interface is reassuring... users don't need +to read obscure documentation in order to have their favorite source +package build shared libraries. They just run your package `configure' +script (or equivalent), and libtool does all the dirty work. + + There are several examples throughout this document. All assume the +same environment: we want to build a library, `libhello', in a generic +way. + + `libhello' could be a shared library, a static library, or both... +whatever is available on the host system, as long as libtool has been +ported to it. + + This chapter explains the original design philosophy of libtool. +Feel free to skip to the next chapter, unless you are interested in +history, or want to write code to extend libtool in a consistent way. + +* Menu: + +* Motivation:: Why does GNU need a libtool? +* Issues:: The problems that need to be addressed. +* Other implementations:: How other people have solved these issues. +* Postmortem:: Learning from past difficulties. + + +File: libtool.info, Node: Motivation, Next: Issues, Up: Introduction + +1.1 Motivation for writing libtool +================================== + +Since early 1995, several different GNU developers have recognized the +importance of having shared library support for their packages. The +primary motivation for such a change is to encourage modularity and +reuse of code (both conceptually and physically) in GNU programs. + + Such a demand means that the way libraries are built in GNU packages +needs to be general, to allow for any library type the package installer +might want. The problem is compounded by the absence of a standard +procedure for creating shared libraries on different platforms. + + The following sections outline the major issues facing shared library +support in GNU, and how shared library support could be standardized +with libtool. + + The following specifications were used in developing and evaluating +this system: + + 1. The system must be as elegant as possible. + + 2. The system must be fully integrated with the GNU Autoconf and + Automake utilities, so that it will be easy for GNU maintainers to + use. However, the system must not require these tools, so that it + can be used by non-GNU packages. + + 3. Portability to other (non-GNU) architectures and tools is + desirable. + + +File: libtool.info, Node: Issues, Next: Other implementations, Prev: Motivation, Up: Introduction + +1.2 Implementation issues +========================= + +The following issues need to be addressed in any reusable shared library +system, specifically libtool: + + 1. The package installer should be able to control what sort of + libraries are built. + + 2. It can be tricky to run dynamically linked programs whose + libraries have not yet been installed. `LD_LIBRARY_PATH' must be + set properly (if it is supported), or programs fail to run. + + 3. The system must operate consistently even on hosts that don't + support shared libraries. + + 4. The commands required to build shared libraries may differ wildly + from host to host. These need to be determined at configure time + in a consistent way. + + 5. It is not always obvious with what prefix or suffix a shared + library should be installed. This makes it difficult for + `Makefile' rules, since they generally assume that file names are + the same from host to host. + + 6. The system needs a simple library version number abstraction, so + that shared libraries can be upgraded in place. The programmer + should be informed how to design the interfaces to the library to + maximize binary compatibility. + + 7. The install `Makefile' target should warn the package installer to + set the proper environment variables (`LD_LIBRARY_PATH' or + equivalent), or run `ldconfig'. + + +File: libtool.info, Node: Other implementations, Next: Postmortem, Prev: Issues, Up: Introduction + +1.3 Other implementations +========================= + +Even before libtool was developed, many free software packages built and +installed their own shared libraries. At first, these packages were +examined to avoid reinventing existing features. + + Now it is clear that none of these packages have documented the +details of shared library systems that libtool requires. So, other +packages have been more or less abandoned as influences. + + +File: libtool.info, Node: Postmortem, Prev: Other implementations, Up: Introduction + +1.4 A postmortem analysis of other implementations +================================================== + +In all fairness, each of the implementations that were examined do the +job that they were intended to do, for a number of different host +systems. However, none of these solutions seem to function well as a +generalized, reusable component. + + Most were too complex to use (much less modify) without understanding +exactly what the implementation does, and they were generally not +documented. + + The main difficulty is that different vendors have different views of +what libraries are, and none of the packages that were examined seemed +to be confident enough to settle on a single paradigm that just _works_. + + Ideally, libtool would be a standard that would be implemented as +series of extensions and modifications to existing library systems to +make them work consistently. However, it is not an easy task to +convince operating system developers to mend their evil ways, and +people want to build shared libraries right now, even on buggy, broken, +confused operating systems. + + For this reason, libtool was designed as an independent shell script. +It isolates the problems and inconsistencies in library building that +plague `Makefile' writers by wrapping the compiler suite on different +platforms with a consistent, powerful interface. + + With luck, libtool will be useful to and used by the GNU community, +and that the lessons that were learned in writing it will be taken up by +designers of future library systems. + + +File: libtool.info, Node: Libtool paradigm, Next: Using libtool, Prev: Introduction, Up: Top + +2 The libtool paradigm +********************** + +At first, libtool was designed to support an arbitrary number of library +object types. After libtool was ported to more platforms, a new +paradigm gradually developed for describing the relationship between +libraries and programs. + + In summary, "libraries are programs with multiple entry points, and +more formally defined interfaces." + + Version 0.7 of libtool was a complete redesign and rewrite of +libtool to reflect this new paradigm. So far, it has proved to be +successful: libtool is simpler and more useful than before. + + The best way to introduce the libtool paradigm is to contrast it with +the paradigm of existing library systems, with examples from each. It +is a new way of thinking, so it may take a little time to absorb, but +when you understand it, the world becomes simpler. + + +File: libtool.info, Node: Using libtool, Next: Invoking libtool, Prev: Libtool paradigm, Up: Top + +3 Using libtool +*************** + +It makes little sense to talk about using libtool in your own packages +until you have seen how it makes your life simpler. The examples in +this chapter introduce the main features of libtool by comparing the +standard library building procedure to libtool's operation on two +different platforms: + +`a23' + An Ultrix 4.2 platform with only static libraries. + +`burger' + A NetBSD/i386 1.2 platform with shared libraries. + + You can follow these examples on your own platform, using the +preconfigured libtool script that was installed with libtool (*note +Configuring::). + + Source files for the following examples are taken from the `demo' +subdirectory of the libtool distribution. Assume that we are building a +library, `libhello', out of the files `foo.c' and `hello.c'. + + Note that the `foo.c' source file uses the `cos' math library +function, which is usually found in the standalone math library, and not +the C library (*note Trigonometric Functions: (libc)Trig Functions.). +So, we need to add `-lm' to the end of the link line whenever we link +`foo.lo' into an executable or a library (*note Inter-library +dependencies::). + + The same rule applies whenever you use functions that don't appear in +the standard C library... you need to add the appropriate `-lNAME' flag +to the end of the link line when you link against those objects. + + After we have built that library, we want to create a program by +linking `main.o' against `libhello'. + +* Menu: + +* Creating object files:: Compiling object files for libraries. +* Linking libraries:: Creating libraries from object files. +* Linking executables:: Linking object files against libtool libraries. +* Debugging executables:: Running GDB on libtool-generated programs. +* Installing libraries:: Making libraries available to users. +* Installing executables:: Making programs available to users. +* Static libraries:: When shared libraries are not wanted. + + +File: libtool.info, Node: Creating object files, Next: Linking libraries, Up: Using libtool + +3.1 Creating object files +========================= + +To create an object file from a source file, the compiler is invoked +with the `-c' flag (and any other desired flags): + + burger$ gcc -g -O -c main.c + burger$ + + The above compiler command produces an object file, usually named +`main.o', from the source file `main.c'. + + For most library systems, creating object files that become part of a +static library is as simple as creating object files that are linked to +form an executable: + + burger$ gcc -g -O -c foo.c + burger$ gcc -g -O -c hello.c + burger$ + + Shared libraries, however, may only be built from +"position-independent code" (PIC). So, special flags must be passed to +the compiler to tell it to generate PIC rather than the standard +position-dependent code. + + Since this is a library implementation detail, libtool hides the +complexity of PIC compiler flags and uses separate library object files +(the PIC one lives in the `.libs' subdirectory and the static one lives +in the current directory). On systems without shared libraries, the +PIC library object files are not created, whereas on systems where all +code is PIC, such as AIX, the static ones are not created. + + To create library object files for `foo.c' and `hello.c', simply +invoke libtool with the standard compilation command as arguments +(*note Compile mode::): + + a23$ libtool --mode=compile gcc -g -O -c foo.c + gcc -g -O -c foo.c -o foo.o + a23$ libtool --mode=compile gcc -g -O -c hello.c + gcc -g -O -c hello.c -o hello.o + a23$ + + Note that libtool silently creates an additional control file on each +`compile' invocation. The `.lo' file is the libtool object, which +Libtool uses to determine what object file may be built into a shared +library. On `a23', only static libraries are supported so the library +objects look like this: + + # foo.lo - a libtool object file + # Generated by ltmain.sh (GNU libtool) 2.4.2 + # + # Please DO NOT delete this file! + # It is necessary for linking the library. + + # Name of the PIC object. + pic_object=none + + # Name of the non-PIC object. + non_pic_object='foo.o' + + On shared library systems, libtool automatically generates an +additional PIC object by inserting the appropriate PIC generation flags +into the compilation command: + + burger$ libtool --mode=compile gcc -g -O -c foo.c + mkdir .libs + gcc -g -O -c foo.c -fPIC -DPIC -o .libs/foo.o + gcc -g -O -c foo.c -o foo.o >/dev/null 2>&1 + burger$ + + Note that Libtool automatically created `.libs' directory upon its +first execution, where PIC library object files will be stored. + + Since `burger' supports shared libraries, and requires PIC objects +to build them, Libtool has compiled a PIC object this time, and made a +note of it in the libtool object: + + # foo.lo - a libtool object file + # Generated by ltmain.sh (GNU libtool) 2.4.2 + # + # Please DO NOT delete this file! + # It is necessary for linking the library. + + # Name of the PIC object. + pic_object='.libs/foo.o' + + # Name of the non-PIC object. + non_pic_object='foo.o' + + Notice that the second run of GCC has its output discarded. This is +done so that compiler warnings aren't annoyingly duplicated. If you +need to see both sets of warnings (you might have conditional code +inside `#ifdef PIC' for example), you can turn off suppression with the +`-no-suppress' option to libtool's compile mode: + + burger$ libtool --mode=compile gcc -no-suppress -g -O -c hello.c + gcc -g -O -c hello.c -fPIC -DPIC -o .libs/hello.o + gcc -g -O -c hello.c -o hello.o + burger$ + + +File: libtool.info, Node: Linking libraries, Next: Linking executables, Prev: Creating object files, Up: Using libtool + +3.2 Linking libraries +===================== + +Without libtool, the programmer would invoke the `ar' command to create +a static library: + + burger$ ar cru libhello.a hello.o foo.o + burger$ + + But of course, that would be too simple, so many systems require that +you run the `ranlib' command on the resulting library (to give it +better karma, or something): + + burger$ ranlib libhello.a + burger$ + + It seems more natural to use the C compiler for this task, given +libtool's "libraries are programs" approach. So, on platforms without +shared libraries, libtool simply acts as a wrapper for the system `ar' +(and possibly `ranlib') commands. + + Again, the libtool control file name (`.la' suffix) differs from the +standard library name (`.a' suffix). The arguments to libtool are the +same ones you would use to produce an executable named `libhello.la' +with your compiler (*note Link mode::): + + a23$ libtool --mode=link gcc -g -O -o libhello.la foo.o hello.o + *** Warning: Linking the shared library libhello.la against the + *** non-libtool objects foo.o hello.o is not portable! + ar cru .libs/libhello.a + ranlib .libs/libhello.a + creating libhello.la + (cd .libs && rm -f libhello.la && ln -s ../libhello.la libhello.la) + a23$ + + Aha! Libtool caught a common error... trying to build a library +from standard objects instead of special `.lo' object files. This +doesn't matter so much for static libraries, but on shared library +systems, it is of great importance. (Note that you may replace +`libhello.la' with `libhello.a' in which case libtool won't issue the +warning any more. But although this method works, this is not intended +to be used because it makes you lose the benefits of using Libtool.) + + So, let's try again, this time with the library object files. +Remember also that we need to add `-lm' to the link command line because +`foo.c' uses the `cos' math library function (*note Using libtool::). + + Another complication in building shared libraries is that we need to +specify the path to the directory in which they (eventually) will be +installed (in this case, `/usr/local/lib')(1): + + a23$ libtool --mode=link gcc -g -O -o libhello.la foo.lo hello.lo \ + -rpath /usr/local/lib -lm + ar cru .libs/libhello.a foo.o hello.o + ranlib .libs/libhello.a + creating libhello.la + (cd .libs && rm -f libhello.la && ln -s ../libhello.la libhello.la) + a23$ + + Now, let's try the same trick on the shared library platform: + + burger$ libtool --mode=link gcc -g -O -o libhello.la foo.lo hello.lo \ + -rpath /usr/local/lib -lm + rm -fr .libs/libhello.a .libs/libhello.la + ld -Bshareable -o .libs/libhello.so.0.0 .libs/foo.o .libs/hello.o -lm + ar cru .libs/libhello.a foo.o hello.o + ranlib .libs/libhello.a + creating libhello.la + (cd .libs && rm -f libhello.la && ln -s ../libhello.la libhello.la) + burger$ + + Now that's significantly cooler... Libtool just ran an obscure `ld' +command to create a shared library, as well as the static library. + + Note how libtool creates extra files in the `.libs' subdirectory, +rather than the current directory. This feature is to make it easier +to clean up the build directory, and to help ensure that other programs +fail horribly if you accidentally forget to use libtool when you should. + + Again, you may want to have a look at the `.la' file in order to see +what Libtool stores in it. In particular, you will see that Libtool +uses this file to remember the destination directory for the library +(the argument to `-rpath') as well as the dependency on the math +library (`-lm'). + + ---------- Footnotes ---------- + + (1) If you don't specify an `rpath', then libtool builds a libtool +convenience archive, not a shared library (*note Static libraries::). + + +File: libtool.info, Node: Linking executables, Next: Debugging executables, Prev: Linking libraries, Up: Using libtool + +3.3 Linking executables +======================= + +If you choose at this point to "install" the library (put it in a +permanent location) before linking executables against it, then you +don't need to use libtool to do the linking. Simply use the appropriate +`-L' and `-l' flags to specify the library's location. + + Some system linkers insist on encoding the full directory name of +each shared library in the resulting executable. Libtool has to work +around this misfeature by special magic to ensure that only permanent +directory names are put into installed executables. + + The importance of this bug must not be overlooked: it won't cause +programs to crash in obvious ways. It creates a security hole, and +possibly even worse, if you are modifying the library source code after +you have installed the package, you will change the behaviour of the +installed programs! + + So, if you want to link programs against the library before you +install it, you must use libtool to do the linking. + + Here's the old way of linking against an uninstalled library: + + burger$ gcc -g -O -o hell.old main.o libhello.a -lm + burger$ + + Libtool's way is almost the same(1) (*note Link mode::): + + a23$ libtool --mode=link gcc -g -O -o hell main.o libhello.la + gcc -g -O -o hell main.o ./.libs/libhello.a -lm + a23$ + + That looks too simple to be true. All libtool did was transform +`libhello.la' to `./.libs/libhello.a', but remember that `a23' has no +shared libraries. Notice that Libtool also remembered that +`libhello.la' depends on `-lm', so even though we didn't specify `-lm' +on the libtool command line(2) Libtool has added it to the `gcc' link +line for us. + + On `burger' Libtool links against the uninstalled shared library: + + burger$ libtool --mode=link gcc -g -O -o hell main.o libhello.la + gcc -g -O -o .libs/hell main.o -L./.libs -R/usr/local/lib -lhello -lm + creating hell + burger$ + + Now assume `libhello.la' had already been installed, and you want to +link a new program with it. You could figure out where it lives by +yourself, then run: + + burger$ gcc -g -O -o test test.o -L/usr/local/lib -lhello -lm + + However, unless `/usr/local/lib' is in the standard library search +path, you won't be able to run `test'. However, if you use libtool to +link the already-installed libtool library, it will do The Right Thing +(TM) for you: + + burger$ libtool --mode=link gcc -g -O -o test test.o \ + /usr/local/lib/libhello.la + gcc -g -O -o .libs/test test.o -Wl,--rpath \ + -Wl,/usr/local/lib /usr/local/lib/libhello.a -lm + creating test + burger$ + + Note that libtool added the necessary run-time path flag, as well as +`-lm', the library libhello.la depended upon. Nice, huh? + + Notice that the executable, `hell', was actually created in the +`.libs' subdirectory. Then, a wrapper script (or, on certain +platforms, a wrapper executable *note Wrapper executables::) was +created in the current directory. + + 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. + + On NetBSD 1.2, libtool encodes the installation directory of +`libhello', by using the `-R/usr/local/lib' compiler flag. Then, the +wrapper script guarantees that the executable finds the correct shared +library (the one in `./.libs') until it is properly installed. + + Let's compare the two different programs: + + burger$ time ./hell.old + Welcome to GNU Hell! + ** This is not GNU Hello. There is no built-in mail reader. ** + 0.21 real 0.02 user 0.08 sys + burger$ time ./hell + Welcome to GNU Hell! + ** This is not GNU Hello. There is no built-in mail reader. ** + 0.63 real 0.09 user 0.59 sys + burger$ + + The wrapper script takes significantly longer to execute, but at +least the results are correct, even though the shared library hasn't +been installed yet. + + So, what about all the space savings that shared libraries are +supposed to yield? + + burger$ ls -l hell.old libhello.a + -rwxr-xr-x 1 gord gord 15481 Nov 14 12:11 hell.old + -rw-r--r-- 1 gord gord 4274 Nov 13 18:02 libhello.a + burger$ ls -l .libs/hell .libs/libhello.* + -rwxr-xr-x 1 gord gord 11647 Nov 14 12:10 .libs/hell + -rw-r--r-- 1 gord gord 4274 Nov 13 18:44 .libs/libhello.a + -rwxr-xr-x 1 gord gord 12205 Nov 13 18:44 .libs/libhello.so.0.0 + burger$ + + Well, that sucks. Maybe I should just scrap this project and take up +basket weaving. + + Actually, it just proves an important point: shared libraries incur +overhead because of their (relative) complexity. In this situation, the +price of being dynamic is eight kilobytes, and the payoff is about four +kilobytes. So, having a shared `libhello' won't be an advantage until +we link it against at least a few more programs. + +* Menu: + +* Wrapper executables:: Wrapper executables for some platforms. + + ---------- Footnotes ---------- + + (1) However, you should avoid using `-L' or `-l' flags to link +against an uninstalled libtool library. Just specify the relative path +to the `.la' file, such as `../intl/libintl.la'. This is a design +decision to eliminate any ambiguity when linking against uninstalled +shared libraries. + + (2) And why should we? `main.o' doesn't directly depend on `-lm' +after all. + + +File: libtool.info, Node: Wrapper executables, Up: Linking executables + +3.3.1 Wrapper executables for uninstalled programs +-------------------------------------------------- + +Some platforms, notably those hosted on Windows such as Cygwin and +MinGW, use a wrapper executable rather than a wrapper script to ensure +proper operation of uninstalled programs linked by libtool against +uninstalled shared libraries. The wrapper executable thus performs the +same function as the wrapper script used on other platforms, but allows +to satisfy the `make' rules for the program, whose name ends in +`$(EXEEXT)'. The actual program executable is created below .libs, and +its name will end in `$(EXEEXT)' and may or may not contain an `lt-' +prefix. This wrapper executable sets various environment values so +that the program executable may locate its (uninstalled) shared +libraries, and then launches the program executable. + + The wrapper executable provides a debug mode, enabled by passing the +command-line option `--lt-debug' (see below). When executing in debug +mode, diagnostic information will be printed to `stderr' before the +program executable is launched. + + Finally, the wrapper executable supports a number of command line +options that may be useful when debugging the operation of the wrapper +system. All of these options begin with `--lt-', and if present they +and their arguments will be removed from the argument list passed on to +the program executable. Therefore, the program executable may not +employ command line options that begin with `--lt-'. (In fact, the +wrapper executable will detect any command line options that begin with +`--lt-' and abort with an error message if the option is not +recognized). If this presents a problem, please contact the Libtool +team at the Libtool bug reporting address . + + These command line options include: + +`--lt-dump-script' + Causes the wrapper to print a copy of the wrapper _script_ to + `stdout', and exit. + +`--lt-debug' + Causes the wrapper to print diagnostic information to `stdout', + before launching the program executable. + + + For consistency, both the wrapper _script_ and the wrapper +_executable_ support these options. + + +File: libtool.info, Node: Debugging executables, Next: Installing libraries, Prev: Linking executables, Up: Using libtool + +3.4 Debugging executables +========================= + +If `hell' was a complicated program, you would certainly want to test +and debug it before installing it on your system. In the above +section, you saw how the libtool wrapper script makes it possible to run +the program directly, but unfortunately, this mechanism interferes with +the debugger: + + burger$ gdb hell + GDB is free software and you are welcome to distribute copies of it + under certain conditions; type "show copying" to see the conditions. + There is no warranty for GDB; type "show warranty" for details. + GDB 4.16 (i386-unknown-netbsd), (C) 1996 Free Software Foundation, Inc. + + "hell": not in executable format: File format not recognized + + (gdb) quit + burger$ + + Sad. It doesn't work because GDB doesn't know where the executable +lives. So, let's try again, by invoking GDB directly on the executable: + + burger$ gdb .libs/hell + GNU gdb 5.3 (i386-unknown-netbsd) + Copyright 2002 Free Software Foundation, Inc. + GDB is free software, covered by the GNU General Public License, + and you are welcome to change it and/or 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) break main + Breakpoint 1 at 0x8048547: file main.c, line 29. + (gdb) run + Starting program: /home/src/libtool/demo/.libs/hell + /home/src/libtool/demo/.libs/hell: can't load library 'libhello.so.0' + + Program exited with code 020. + (gdb) quit + burger$ + + Argh. Now GDB complains because it cannot find the shared library +that `hell' is linked against. So, we must use libtool in order to +properly set the library path and run the debugger. Fortunately, we can +forget all about the `.libs' directory, and just run it on the +executable wrapper (*note Execute mode::): + + burger$ libtool --mode=execute gdb hell + GNU gdb 5.3 (i386-unknown-netbsd) + Copyright 2002 Free Software Foundation, Inc. + GDB is free software, covered by the GNU General Public License, + and you are welcome to change it and/or 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) break main + Breakpoint 1 at 0x8048547: file main.c, line 29. + (gdb) run + Starting program: /home/src/libtool/demo/.libs/hell + + Breakpoint 1, main (argc=1, argv=0xbffffc40) at main.c:29 + 29 printf ("Welcome to GNU Hell!\n"); + (gdb) quit + The program is running. Quit anyway (and kill it)? (y or n) y + burger$ + + +File: libtool.info, Node: Installing libraries, Next: Installing executables, Prev: Debugging executables, Up: Using libtool + +3.5 Installing libraries +======================== + +Installing libraries on a non-libtool system is quite +straightforward... just copy them into place:(1) + + burger$ su + Password: ******** + burger# cp libhello.a /usr/local/lib/libhello.a + burger# + + Oops, don't forget the `ranlib' command: + + burger# ranlib /usr/local/lib/libhello.a + burger# + + Libtool installation is quite simple, as well. Just use the +`install' or `cp' command that you normally would (*note Install +mode::): + + a23# libtool --mode=install cp libhello.la /usr/local/lib/libhello.la + cp libhello.la /usr/local/lib/libhello.la + cp .libs/libhello.a /usr/local/lib/libhello.a + ranlib /usr/local/lib/libhello.a + a23# + + Note that the libtool library `libhello.la' is also installed, to +help libtool with uninstallation (*note Uninstall mode::) and linking +(*note Linking executables::) and to help programs with dlopening +(*note Dlopened modules::). + + Here is the shared library example: + + burger# libtool --mode=install install -c libhello.la \ + /usr/local/lib/libhello.la + install -c .libs/libhello.so.0.0 /usr/local/lib/libhello.so.0.0 + install -c libhello.la /usr/local/lib/libhello.la + install -c .libs/libhello.a /usr/local/lib/libhello.a + ranlib /usr/local/lib/libhello.a + burger# + + It is safe to specify the `-s' (strip symbols) flag if you use a +BSD-compatible install program when installing libraries. Libtool will +either ignore the `-s' flag, or will run a program that will strip only +debugging and compiler symbols from the library. + + Once the libraries have been put in place, there may be some +additional configuration that you need to do before using them. First, +you must make sure that where the library is installed actually agrees +with the `-rpath' flag you used to build it. + + Then, running `libtool -n finish LIBDIR' can give you further hints +on what to do (*note Finish mode::): + + burger# libtool -n finish /usr/local/lib + PATH="$PATH:/sbin" ldconfig -m /usr/local/lib + ----------------------------------------------------------------- + Libraries have been installed in: + /usr/local/lib + + To link against installed libraries in a given directory, LIBDIR, + you must use the `-LLIBDIR' flag during linking. + + You will also need to do one of the following: + - add LIBDIR to the `LD_LIBRARY_PATH' environment variable + during execution + - add LIBDIR to the `LD_RUN_PATH' environment variable + during linking + - use the `-RLIBDIR' linker flag + + See any operating system documentation about shared libraries for + more information, such as the ld and ld.so manual pages. + ----------------------------------------------------------------- + burger# + + After you have completed these steps, you can go on to begin using +the installed libraries. You may also install any executables that +depend on libraries you created. + + ---------- Footnotes ---------- + + (1) Don't strip static libraries though, or they will be unusable. + + +File: libtool.info, Node: Installing executables, Next: Static libraries, Prev: Installing libraries, Up: Using libtool + +3.6 Installing executables +========================== + +If you used libtool to link any executables against uninstalled libtool +libraries (*note Linking executables::), you need to use libtool to +install the executables after the libraries have been installed (*note +Installing libraries::). + + So, for our Ultrix example, we would run: + + a23# libtool --mode=install -c hell /usr/local/bin/hell + install -c hell /usr/local/bin/hell + a23# + + On shared library systems that require wrapper scripts, libtool just +ignores the wrapper script and installs the correct binary: + + burger# libtool --mode=install -c hell /usr/local/bin/hell + install -c .libs/hell /usr/local/bin/hell + burger# + + +File: libtool.info, Node: Static libraries, Prev: Installing executables, Up: Using libtool + +3.7 Linking static libraries +============================ + +Why return to `ar' and `ranlib' silliness when you've had a taste of +libtool? Well, sometimes it is desirable to create a static archive +that can never be shared. The most frequent case is when you have a +set of object files that you use to build several different libraries. +You can create a "convenience library" out of those objects, and link +against that with the other libraries, instead of listing all the +object files every time. + + If you just want to link this convenience library into programs, then +you could just ignore libtool entirely, and use the old `ar' and +`ranlib' commands (or the corresponding GNU Automake `_LIBRARIES' +rules). You can even install a convenience library using GNU Libtool, +though you probably don't want to and hence GNU Automake doesn't allow +you to do so. + + burger$ libtool --mode=install ./install-sh -c libhello.a \ + /local/lib/libhello.a + ./install-sh -c libhello.a /local/lib/libhello.a + ranlib /local/lib/libhello.a + burger$ + + Using libtool for static library installation protects your library +from being accidentally stripped (if the installer used the `-s' flag), +as well as automatically running the correct `ranlib' command. + + But libtool libraries are more than just collections of object files: +they can also carry library dependency information, which old archives +do not. If you want to create a libtool static convenience library, you +can omit the `-rpath' flag and use `-static' to indicate that you're +only interested in a static library. When you link a program with such +a library, libtool will actually link all object files and dependency +libraries into the program. + + If you omit both `-rpath' and `-static', libtool 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. + + The key is remembering that a convenience library contains PIC +objects, and can be linked where a list of PIC objects makes sense; +i.e. into a shared library. A static convenience library contains +non-PIC objects, so can be linked into an old static library, or a +program. + + When GNU Automake is used, you should use `noinst_LTLIBRARIES' +instead of `lib_LTLIBRARIES' for convenience libraries, so that the +`-rpath' option is not passed when they are linked. + + As a rule of thumb, link a libtool convenience library into at most +one libtool library, and never into a program, and link libtool static +convenience libraries only into programs, and only if you need to carry +library dependency information to the user of the static convenience +library. + + Another common situation where static linking is desirable is in +creating a standalone binary. Use libtool to do the linking and add the +`-all-static' flag. + + +File: libtool.info, Node: Invoking libtool, Next: Integrating libtool, Prev: Using libtool, Up: Top + +4 Invoking `libtool' +******************** + +The `libtool' program has the following synopsis: + + libtool [OPTION]... [MODE-ARG]... + +and accepts the following options: + +`--config' + Display libtool configuration variables and exit. + +`--debug' + Dump a trace of shell script execution to standard output. This + produces a lot of output, so you may wish to pipe it to `less' (or + `more') or redirect to a file. + +`-n' +`--dry-run' + Don't create, modify, or delete any files, just show what commands + would be executed by libtool. + +`--features' + Display basic configuration options. This provides a way for + packages to determine whether shared or static libraries will be + built. + +`--finish' + Same as `--mode=finish'. + +`-h' + Display short help message. + +`--help' + Display a help message and exit. If `--mode=MODE' is specified, + then detailed help for MODE is displayed. + +`--help-all' + Display help for the general options as well as detailed help for + each operation mode, and exit. + +`--mode=MODE' + Use MODE as the operation mode. When using libtool from the + command line, you can give just MODE (or a unique abbreviation of + it) as the first argument as a shorthand for the full + `--mode=MODE'. For example, the following are equivalent: + + $ libtool --mode=execute --dry-run gdb prog.exe + $ libtool execute --dry-run gdb prog.exe + $ libtool exe --dry-run gdb prog.exe + $ libtool e --dry-run gdb prog.exe + + MODE must be set to one of the following: + + `compile' + Compile a source file into a libtool object. + + `execute' + Automatically set the library path so that another program + can use uninstalled libtool-generated programs or libraries. + + `link' + Create a library or an executable. + + `install' + Install libraries or executables. + + `finish' + Complete the installation of libtool libraries on the system. + + `uninstall' + Delete installed libraries or executables. + + `clean' + Delete uninstalled libraries or executables. + +`--tag=TAG' + Use configuration variables from tag TAG (*note Tags::). + +`--preserve-dup-deps' + Do not remove duplicate dependencies in libraries. When building + packages with static libraries, the libraries may depend + circularly on each other (shared libs can too, but for those it + doesn't matter), so there are situations, where -la -lb -la is + required, and the second -la may not be stripped or the link will + fail. In cases where these duplications are required, this option + will preserve them, only stripping the libraries that libtool + knows it can safely. + +`--quiet' +`--silent' + Do not print out any progress or informational messages. + +`-v' +`--verbose' + Print out progress and informational messages (enabled by default), + as well as additional messages not ordinary seen by default. + +`--no-quiet' +`--no-silent' + Print out the progress and informational messages that are seen by + default. This option has no effect on whether the additional + messages seen in `--verbose' mode are shown. + +`--no-verbose' + Do not print out any additional informational messages beyond + those ordinarily seen by default. This option has no effect on + whether the ordinary progress and informational messages enabled + by `--no-quiet' are shown. + + Thus, there are now three different message levels (not counting + `--debug'), depending on whether the normal messages and/or the + additional verbose messages are displayed. Note that there is no + mechanism to diplay verbose messages, without also displaying + normal messages. + + *default* + Normal messages are displayed, verbose messages are not + displayed. In addition to being the default mode, it can be + forcibly achieved by using both option `--no-verbose' and + either option `--no-silent' or option `--no-quiet'. + + *silent* + Neither normal messages nor verbose messages are displayed. + This mode can be achieved using either option `--silent' or + option `--quiet'. + + *verbose* + Both normal messages and verbose messages are displayed. This + mode can be achieved using either option `-v' or option + `--verbose'. + +`--version' + Print libtool version information and exit. + + The current `libtool' implementation is done with a shell script +that needs to be invoked by the shell which `configure' chose for +configuring `libtool' (*note The Autoconf Manual: +(autoconf)config.status Invocation.). This shell is set in the +she-bang (`#!') line of the `libtool' script. Using a different shell +may cause undefined behavior. + + The MODE-ARGS are a variable number of arguments, depending on the +selected operation mode. In general, each MODE-ARG is interpreted by +programs libtool invokes, rather than libtool itself. + +* Menu: + +* Compile mode:: Creating library object files. +* Link mode:: Generating executables and libraries. +* Execute mode:: Debugging libtool-generated programs. +* Install mode:: Making libraries and executables public. +* Finish mode:: Completing a library installation. +* Uninstall mode:: Removing installed executables and libraries. +* Clean mode:: Removing uninstalled executables and libraries. + + +File: libtool.info, Node: Compile mode, Next: Link mode, Up: Invoking libtool + +4.1 Compile mode +================ + +For "compile" mode, MODE-ARGS is a compiler command to be used in +creating a "standard" object file. These arguments should begin with +the name of the C compiler, and contain the `-c' compiler flag so that +only an object file is created. + + Libtool determines the name of the output file by removing the +directory component from the source file name, then substituting the +source code suffix (e.g. `.c' for C source code) with the library +object suffix, `.lo'. + + If shared libraries are being built, any necessary PIC generation +flags are substituted into the compilation command. + + The following components of MODE-ARGS are treated specially: + +`-o' + Note that the `-o' option is now fully supported. It is emulated + on the platforms that don't support it (by locking and moving the + objects), so it is really easy to use libtool, just with minor + modifications to your Makefiles. Typing for example + libtool --mode=compile gcc -c foo/x.c -o foo/x.lo + will do what you expect. + + Note, however, that, if the compiler does not support `-c' and + `-o', it is impossible to compile `foo/x.c' without overwriting an + existing `./x.o'. Therefore, if you do have a source file + `./x.c', make sure you introduce dependencies in your `Makefile' + to make sure `./x.o' (or `./x.lo') is re-created after any + sub-directory's `x.lo': + + x.o x.lo: foo/x.lo bar/x.lo + + This will also ensure that make won't try to use a temporarily + corrupted `x.o' to create a program or library. It may cause + needless recompilation on platforms that support `-c' and `-o' + together, but it's the only way to make it safe for those that + don't. + +`-no-suppress' + If both PIC and non-PIC objects are being built, libtool will + normally suppress the compiler output for the PIC object + compilation to save showing very similar, if not identical + duplicate output for each object. If the `-no-suppress' option is + given in compile mode, libtool will show the compiler output for + both objects. + +`-prefer-pic' + Libtool will try to build only PIC objects. + +`-prefer-non-pic' + Libtool will try to build only non-PIC objects. + +`-shared' + Even if Libtool was configured with `--enable-static', the object + file Libtool builds will not be suitable for static linking. + Libtool will signal an error if it was configured with + `--disable-shared', or if the host does not support shared + libraries. + +`-static' + Even if libtool was configured with `--disable-static', the object + file Libtool builds *will* be suitable for static linking. + +`-Wc,FLAG' +`-Xcompiler FLAG' + Pass a flag directly to the compiler. With `-Wc,', multiple flags + may be separated by commas, whereas `-Xcompiler ' passes through + commas unchanged. + + +File: libtool.info, Node: Link mode, Next: Execute mode, Prev: Compile mode, Up: Invoking libtool + +4.2 Link mode +============= + +"Link" mode links together object files (including library objects) to +form another library or to create an executable program. + + MODE-ARGS consist of a command using the C compiler to create an +output file (with the `-o' flag) from several object files. + + The following components of MODE-ARGS are treated specially: + +`-all-static' + If OUTPUT-FILE is a program, then do not link it against any + shared libraries at all. If OUTPUT-FILE is a library, then only + create a static library. In general, this flag cannot be used + together with `disable-static' (*note LT_INIT::). + +`-avoid-version' + Tries to avoid versioning (*note Versioning::) for libraries and + modules, i.e. no version information is stored and no symbolic + links are created. If the platform requires versioning, this + option has no effect. + +`-bindir' + Pass the absolute name of the directory for installing executable + programs (*note Directory Variables: (standards)Directory + Variables.). `libtool' may use this value to install shared + libraries there on systems that do not provide for any library + hardcoding and use the directory of a program and the `PATH' + variable as library search path. This is typically used for DLLs + on Windows or other systems using the PE (Portable Executable) + format. On other systems, `-bindir' is ignored. The default + value used is `LIBDIR/../bin' for libraries installed to `LIBDIR'. + You should not use `-bindir' for modules. + +`-dlopen FILE' + Same as `-dlpreopen FILE', if native dlopening is not supported on + the host platform (*note Dlopened modules::) or if the program is + linked with `-static', `-static-libtool-libs', or `-all-static'. + Otherwise, no effect. If FILE is `self' Libtool will make sure + that the program can `dlopen' itself, either by enabling + `-export-dynamic' or by falling back to `-dlpreopen self'. + +`-dlpreopen FILE' + Link FILE into the output program, and add its symbols to the list + of preloaded symbols (*note Dlpreopening::). If FILE is `self', + the symbols of the program itself will be added to preloaded + symbol lists. If FILE is `force' Libtool will make sure that a + preloaded symbol list is always _defined_, regardless of whether + it's empty or not. + +`-export-dynamic' + Allow symbols from OUTPUT-FILE to be resolved with `dlsym' (*note + Dlopened modules::). + +`-export-symbols SYMFILE' + Tells the linker to export only the symbols listed in SYMFILE. + The symbol file should end in `.sym' and must contain the name of + one symbol per line. This option has no effect on some platforms. + By default all symbols are exported. + +`-export-symbols-regex REGEX' + Same as `-export-symbols', except that only symbols matching the + regular expression REGEX are exported. By default all symbols are + exported. + +`-LLIBDIR' + Search LIBDIR for required libraries that have already been + installed. + +`-lNAME' + OUTPUT-FILE requires the installed library `libNAME'. This option + is required even when OUTPUT-FILE is not an executable. + +`-module' + Creates a library that can be dlopened (*note Dlopened modules::). + This option doesn't work for programs. Module names don't need to + be prefixed with `lib'. In order to prevent name clashes, + however, `libNAME' and `NAME' must not be used at the same time in + your package. + +`-no-fast-install' + Disable fast-install mode for the executable OUTPUT-FILE. Useful + if the program won't be necessarily installed. + +`-no-install' + Link an executable OUTPUT-FILE that can't be installed and + therefore doesn't need a wrapper script on systems that allow + hardcoding of library paths. Useful if the program is only used + in the build tree, e.g., for testing or generating other files. + +`-no-undefined' + Declare that OUTPUT-FILE does not depend on any libraries other + than the ones listed on the command line, i.e., after linking, it + will not have unresolved symbols. Some platforms require all + symbols in shared libraries to be resolved at library creation + (*note Inter-library dependencies::), and using this parameter + allows `libtool' to assume that this will not happen. + +`-o OUTPUT-FILE' + Create OUTPUT-FILE from the specified objects and libraries. + +`-objectlist FILE' + Use a list of object files found in FILE to specify objects. + +`-precious-files-regex REGEX' + Prevents removal of files from the temporary output directory whose + names match this regular expression. You might specify `\.bbg?$' + to keep those files created with `gcc -ftest-coverage' for example. + +`-release RELEASE' + Specify that the library was generated by release RELEASE of your + package, so that users can easily tell which versions are newer + than others. Be warned that no two releases of your package will + be binary compatible if you use this flag. If you want binary + compatibility, use the `-version-info' flag instead (*note + Versioning::). + +`-rpath LIBDIR' + If OUTPUT-FILE is a library, it will eventually be installed in + LIBDIR. If OUTPUT-FILE is a program, add LIBDIR to the run-time + path of the program. On platforms that don't support hardcoding + library paths into executables and only search PATH for shared + libraries, such as when OUTPUT-FILE is a Windows (or other PE + platform) DLL, the `.la' control file will be installed in LIBDIR, + but see `-bindir' above for the eventual destination of the `.dll' + or other library file itself. + +`-R LIBDIR' + If OUTPUT-FILE is a program, add LIBDIR to its run-time path. If + OUTPUT-FILE is a library, add `-RLIBDIR' to its DEPENDENCY_LIBS, + so that, whenever the library is linked into a program, LIBDIR + will be added to its run-time path. + +`-shared' + If OUTPUT-FILE is a program, then link it against any uninstalled + shared libtool libraries (this is the default behavior). If + OUTPUT-FILE is a library, then only create a shared library. In + the later case, libtool will signal an error if it was configured + with `--disable-shared', or if the host does not support shared + libraries. + +`-shrext SUFFIX' + If OUTPUT-FILE is a libtool library, replace the system's standard + file name extension for shared libraries with SUFFIX (most systems + use `.so' here). This option is helpful in certain cases where an + application requires that shared libraries (typically modules) + have an extension other than the default one. Please note you + must supply the full file name extension including any leading dot. + +`-static' + If OUTPUT-FILE is a program, then do not link it against any + uninstalled shared libtool libraries. If OUTPUT-FILE is a + library, then only create a static library. + +`-static-libtool-libs' + If OUTPUT-FILE is a program, then do not link it against any + shared libtool libraries. If OUTPUT-FILE is a library, then only + create a static library. + +`-version-info CURRENT[:REVISION[:AGE]]' + If OUTPUT-FILE is a libtool library, use interface version + information CURRENT, REVISION, and AGE to build it (*note + Versioning::). Do *not* use this flag to specify package release + information, rather see the `-release' flag. + +`-version-number MAJOR[:MINOR[:REVISION]]' + If OUTPUT-FILE is a libtool library, compute interface version + information so that the resulting library uses the specified + major, minor and revision numbers. This is designed to permit + libtool to be used with existing projects where identical version + numbers are already used across operating systems. New projects + should use the `-version-info' flag instead. + +`-weak LIBNAME' + if OUTPUT-FILE is a libtool library, declare that it provides a + weak LIBNAME interface. This is a hint to libtool that there is + no need to append LIBNAME to the list of dependency libraries of + OUTPUT-FILE, because linking against OUTPUT-FILE already supplies + the same interface (*note Linking with dlopened modules::). + +`-Wc,FLAG' +`-Xcompiler FLAG' + Pass a linker-specific flag directly to the compiler. With `-Wc,', + multiple flags may be separated by commas, whereas `-Xcompiler ' + passes through commas unchanged. + +`-Wl,FLAG' +`-Xlinker FLAG' + Pass a linker-specific flag directly to the linker. + +`-XCClinker FLAG' + Pass a link-specific flag to the compiler driver (`CC') during + linking. + + If the OUTPUT-FILE ends in `.la', then a libtool library is created, +which must be built only from library objects (`.lo' files). The +`-rpath' option is required. In the current implementation, libtool +libraries may not depend on other uninstalled libtool libraries (*note +Inter-library dependencies::). + + If the OUTPUT-FILE ends in `.a', then a standard library is created +using `ar' and possibly `ranlib'. + + If OUTPUT-FILE ends in `.o' or `.lo', then a reloadable object file +is created from the input files (generally using `ld -r'). This method +is often called "partial linking". + + Otherwise, an executable program is created. + + +File: libtool.info, Node: Execute mode, Next: Install mode, Prev: Link mode, Up: Invoking libtool + +4.3 Execute mode +================ + +For "execute" mode, the library path is automatically set, then a +program is executed. + + The first of the MODE-ARGS is treated as a program name, with the +rest as arguments to that program. + + The following components of MODE-ARGS are treated specially: + +`-dlopen FILE' + Add the directory containing FILE to the library path. + + This mode sets the library path environment variable according to any +`-dlopen' flags. + + If any of the ARGS are libtool executable wrappers, then they are +translated into the name of their corresponding uninstalled binary, and +any of their required library directories are added to the library path. + + +File: libtool.info, Node: Install mode, Next: Finish mode, Prev: Execute mode, Up: Invoking libtool + +4.4 Install mode +================ + +In "install" mode, libtool interprets most of the elements of MODE-ARGS +as an installation command beginning with `cp', or a BSD-compatible +`install' program. + + The following components of MODE-ARGS are treated specially: + +`-inst-prefix-dir INST-PREFIX-DIR' + When installing into a temporary staging area, rather than the + final `prefix', this argument is used to reflect the temporary + path, in much the same way `automake' uses `DESTDIR'. For + instance, if `prefix' is `/usr/local', but INST-PREFIX-DIR is + `/tmp', then the object will be installed under `/tmp/usr/local/'. + If the installed object is a libtool library, then the internal + fields of that library will reflect only `prefix', not + INST-PREFIX-DIR: + + # Directory that this library needs to be installed in: + libdir='/usr/local/lib' + + not + + # Directory that this library needs to be installed in: + libdir='/tmp/usr/local/lib' + + `inst-prefix' is also used to insure that if the installed object + must be relinked upon installation, that it is relinked against + the libraries in INST-PREFIX-DIR/`prefix', not `prefix'. + + In truth, this option is not really intended for use when calling + libtool directly; it is automatically used when `libtool + --mode=install' calls `libtool --mode=relink'. Libtool does this + by analyzing the destination path given in the original `libtool + --mode=install' command and comparing it to the expected + installation path established during `libtool --mode=link'. + + Thus, end-users need change nothing, and `automake'-style `make + install DESTDIR=/tmp' will Just Work(tm) most of the time. For + systems where fast installation can not be turned on, relinking + may be needed. In this case, a `DESTDIR' install will fail. + + Currently it is not generally possible to install into a temporary + staging area that contains needed third-party libraries which are + not yet visible at their final location. + + The rest of the MODE-ARGS are interpreted as arguments to the `cp' +or `install' command. + + The command is run, and any necessary unprivileged post-installation +commands are also completed. + + +File: libtool.info, Node: Finish mode, Next: Uninstall mode, Prev: Install mode, Up: Invoking libtool + +4.5 Finish mode +=============== + +"Finish" mode has two functions. One is to help system administrators +install libtool libraries so that they can be located and linked into +user programs. To invoke this functionality, pass the name of a library +directory as MODE-ARG. Running this command may require superuser +privileges, and the `--dry-run' option may be useful. + + The second is to facilitate transferring libtool libraries to a +native compilation environment after they were built in a +cross-compilation environment. Cross-compilation environments may rely +on recent libtool features, and running libtool in finish mode will +make it easier to work with older versions of libtool. This task is +performed whenever the MODE-ARG is a `.la' file. + + +File: libtool.info, Node: Uninstall mode, Next: Clean mode, Prev: Finish mode, Up: Invoking libtool + +4.6 Uninstall mode +================== + +"Uninstall" mode deletes installed libraries, executables and objects. + + The first MODE-ARG is the name of the program to use to delete files +(typically `/bin/rm'). + + The remaining MODE-ARGS are either flags for the deletion program +(beginning with a `-'), or the names of files to delete. + + +File: libtool.info, Node: Clean mode, Prev: Uninstall mode, Up: Invoking libtool + +4.7 Clean mode +============== + +"Clean" mode deletes uninstalled libraries, executables, objects and +libtool's temporary files associated with them. + + The first MODE-ARG is the name of the program to use to delete files +(typically `/bin/rm'). + + The remaining MODE-ARGS are either flags for the deletion program +(beginning with a `-'), or the names of files to delete. + + +File: libtool.info, Node: Integrating libtool, Next: Other languages, Prev: Invoking libtool, Up: Top + +5 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. + + There are several ways in which Libtool may be integrated in your +package, described in the following sections. Typically, the Libtool +macro files as well as `ltmain.sh' are copied into your package using +`libtoolize' and `aclocal' after setting up the `configure.ac' and +toplevel `Makefile.am', then `autoconf' adds the needed tests to the +`configure' script. These individual steps are often automated with +`autoreconf'. + + Here is a diagram showing how such a typical Libtool configuration +works when preparing a package for distribution, assuming that `m4' has +been chosen as location for additional Autoconf macros, and `build-aux' +as location for auxiliary build tools (*note The Autoconf Manual: +(autoconf)Input.): + + libtool.m4 -----. .--> aclocal.m4 -----. + ltoptions.m4 ---+ .-> aclocal* -+ +--> autoconf* + ltversion.m4 ---+--+ `--> [copy in m4/] --+ | + ltsugar.m4 -----+ | ^ | \/ + lt~obsolete.m4 -+ +-> libtoolize* -----' | configure + [ltdl.m4] ------+ | | + `----------------------------------' + + ltmain.sh -----------> libtoolize* -> [copy in build-aux/] + + During configuration, the `libtool' script is generated either +through `config.status' or `config.lt': + + .--> config.status* --. + configure* --+ +--> libtool + `--> [config.lt*] ----' ^ + | + ltmain.sh --------------------------------' + + At `make' run time, `libtool' is then invoked as needed as a wrapper +around compilers, linkers, install and cleanup programs. + + There are alternatives choices to several parts of the setup; for +example, the Libtool macro files can either be copied or symlinked into +the package, or copied into `aclocal.m4'. As another example, an +external, pre-configured `libtool' script may be used, by-passing most +of the tests and package-specific setup for Libtool. + +* Menu: + +* Autoconf macros:: Autoconf macros exported by libtool. +* Makefile rules:: Writing `Makefile' rules for libtool. +* Using Automake:: Automatically supporting libtool. +* Configuring:: Configuring libtool for a host system. +* Distributing:: What files to distribute with your package. +* Static-only libraries:: Sometimes shared libraries are just a pain. + + +File: libtool.info, Node: Autoconf macros, Next: Makefile rules, Up: Integrating libtool + +5.1 Autoconf macros exported by libtool +======================================= + +Libtool uses a number of macros to interrogate the host system when it +is being built, and you can use some of them yourself too. Although +there are a great many other macros in the libtool installed m4 files, +these do not form part of the published interface, and are subject to +change between releases. + +Macros in the `LT_CMD_' namespace check for various shell commands: + + -- Macro: LT_CMD_MAX_LEN + Finds the longest command line that can be safely passed to + `$SHELL' without being truncated, and store in the shell variable + `$max_cmd_len'. It is only an approximate value, but command + lines of this length or shorter are guaranteed not to be truncated. + +Macros in the `LT_FUNC_' namespace check characteristics of library +functions: + + -- Macro: LT_FUNC_DLSYM_USCORE + `AC_DEFINE' the preprocessor symbol `DLSYM_USCORE' if we have to + add an underscore to symbol-names passed in to `dlsym'. + +Macros in the `LT_LIB_' namespace check characteristics of system +libraries: + + -- Macro: LT_LIB_M + Set `LIBM' to the math library or libraries required on this + machine, if any. + + -- Macro: LT_LIB_DLLOAD + This is the macro used by `libltdl' to determine which dlloaders + to use on this machine, if any. Several shell variables are set + (and `AC_SUBST'ed) depending on the dlload interfaces are + available on this machine. `LT_DLLOADERS' contains a list of + libtool libraries that can be used, and if necessary also sets + `LIBADD_DLOPEN' if additional system libraries are required by the + `dlopen' loader, and `LIBADD_SHL_LOAD' if additional system + libraries are required by the `shl_load' loader, respectively. + Finally some symbols are set in `config.h' depending on the + loaders that are found to work: `HAVE_LIBDL', `HAVE_SHL_LOAD', + `HAVE_DYLD', `HAVE_DLD'. + +Macros in the `LT_PATH_' namespace search the system for the full path +to particular system commands: + + -- Macro: LT_PATH_LD + Add a `--with-gnu-ld' option to `configure'. Try to find the path + to the linker used by `$CC', and whether it is the GNU linker. + The result is stored in the shell variable `$LD', which is + `AC_SUBST'ed. + + -- Macro: LT_PATH_NM + Try to find a BSD-compatible `nm' or a MS-compatible `dumpbin' + command on this machine. The result is stored in the shell + variable `$NM', which is `AC_SUBST'ed. + +Macros in the `LT_SYS_' namespace probe for system characteristics: + + -- Macro: LT_SYS_DLOPEN_SELF + Tests whether a program can dlopen itself, and then also whether + the same program can still dlopen itself when statically linked. + Results are stored in the shell variables `$enable_dlopen_self' and + `enable_dlopen_self_static' respectively. + + -- Macro: LT_SYS_DLOPEN_DEPLIBS + Define the preprocessor symbol `LTDL_DLOPEN_DEPLIBS' if the OS + needs help to load dependent libraries for `dlopen' (or + equivalent). + + -- Macro: LT_SYS_DLSEARCH_PATH + Define the preprocessor symbol `LT_DLSEARCH_PATH' to the system + default library search path. + + -- Macro: LT_SYS_MODULE_EXT + Define the preprocessor symbol `LT_MODULE_EXT' to the extension + used for runtime loadable modules. If you use libltdl to open + modules, then you can simply use the libtool library extension, + `.la'. + + -- Macro: LT_SYS_MODULE_PATH + Define the preprocessor symbol `LT_MODULE_PATH_VAR' to the name of + the shell environment variable that determines the run-time module + search path. + + -- Macro: LT_SYS_SYMBOL_USCORE + Set the shell variable `sys_symbol_underscore' to `no' unless the + compiler prefixes global symbols with an underscore. + + +File: libtool.info, Node: Makefile rules, Next: Using Automake, Prev: Autoconf macros, Up: Integrating libtool + +5.2 Writing `Makefile' rules for libtool +======================================== + +Libtool is fully integrated with Automake (*note Introduction: +(automake)Top.), starting with Automake version 1.2. + + If you want to use libtool in a regular `Makefile' (or +`Makefile.in'), you are on your own. If you're not using Automake, and +you don't know how to incorporate libtool into your package you need to +do one of the following: + + 1. Download the latest Automake distribution from your nearest GNU + mirror, install it, and start using it. + + 2. Learn how to write `Makefile' rules by hand. They're sometimes + complex, but if you're clever enough to write rules for compiling + your old libraries, then you should be able to figure out new + rules for libtool libraries (hint: examine the `Makefile.in' in + the `tests/demo' subdirectory of the libtool distribution... note + especially that it was automatically generated from the + `Makefile.am' by Automake). + + +File: libtool.info, Node: Using Automake, Next: Configuring, Prev: Makefile rules, Up: Integrating libtool + +5.3 Using Automake with libtool +=============================== + +Libtool library support is implemented under the `LTLIBRARIES' primary. + + Here are some samples from the Automake `Makefile.am' in the libtool +distribution's `demo' subdirectory. + + First, to link a program against a libtool library, just use the +`program_LDADD'(1) variable: + + bin_PROGRAMS = hell hell_static + + # Build hell from main.c and libhello.la + hell_SOURCES = main.c + hell_LDADD = libhello.la + + # Create a statically linked version of hell. + hell_static_SOURCES = main.c + hell_static_LDADD = libhello.la + hell_static_LDFLAGS = -static + + You may use the `program_LDFLAGS' variable to stuff in any flags you +want to pass to libtool while linking `program' (such as `-static' to +avoid linking uninstalled shared libtool libraries). + + Building a libtool library is almost as trivial... note the use of +`libhello_la_LDFLAGS' to pass the `-version-info' (*note Versioning::) +option to libtool: + + # 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 + + The `-rpath' option is passed automatically by Automake (except for +libraries listed as `noinst_LTLIBRARIES'), so you should not specify it. + + *Note Building a Shared Library: (automake)A Shared Library, for +more information. + + ---------- Footnotes ---------- + + (1) Since GNU Automake 1.5, the flags `-dlopen' or `-dlpreopen' +(*note Link mode::) can be employed with the `program_LDADD' variable. +Unfortunately, older releases didn't accept these flags, so if you are +stuck with an ancient Automake, we recommend quoting the flag itself, +and setting `program_DEPENDENCIES' too: + + program_LDADD = "-dlopen" libfoo.la + program_DEPENDENCIES = libfoo.la + + +File: libtool.info, Node: Configuring, Next: Distributing, Prev: Using Automake, Up: Integrating libtool + +5.4 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 (*note +Distributing::), you do not always know the compiler suite and +operating system that are used to compile your package. + + For this reason, libtool must be "configured" before it can be used. +This idea should be familiar to anybody who has used a GNU `configure' +script. `configure' runs a number of tests for system features, then +generates the `Makefile's (and possibly a `config.h' header file), +after which you can run `make' and build the package. + + Libtool adds its own tests to your `configure' script in order to +generate a libtool script for the installer's host machine. + +* Menu: + +* LT_INIT:: Configuring `libtool' in `configure.ac'. +* Configure notes:: Platform-specific notes for configuration. + + +File: libtool.info, Node: LT_INIT, Next: Configure notes, Up: Configuring + +5.4.1 The `LT_INIT' macro +------------------------- + +If you are using GNU Autoconf (or Automake), you should add a call to +`LT_INIT' to your `configure.ac' file. This macro adds many new tests +to the `configure' script so that the generated libtool script will +understand the characteristics of the host. It's the most important of +a number of macros defined by Libtool: + + -- Macro: LT_PREREQ (VERSION) + Ensure that a recent enough version of Libtool is being used. If + the version of Libtool used for `LT_INIT' is earlier than VERSION, + print an error message to the standard error output and exit with + failure (exit status is 63). For example: + + LT_PREREQ([2.4.2]) + + -- Macro: LT_INIT (OPTIONS) + -- Macro: AC_PROG_LIBTOOL + -- Macro: AM_PROG_LIBTOOL + Add support for the `--enable-shared', `--disable-shared', + `--enable-static', `--disable-static', `--with-pic', and + `--without-pic' `configure' flags.(1) `AC_PROG_LIBTOOL' and + `AM_PROG_LIBTOOL' are deprecated names for older versions of this + macro; `autoupdate' will upgrade your `configure.ac' files. + + 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 passing either `disable-shared' or `disable-static' in the + option list to `LT_INIT', or using `AC_DISABLE_SHARED' or + `AC_DISABLE_STATIC'. + + # Turn off shared libraries during beta-testing, since they + # make the build process take too long. + LT_INIT([disable-shared]) + + The user may specify modified forms of the configure flags + `--enable-shared' and `--enable-static' to choose whether shared + or static libraries are built based on the name of the package. + For example, to have shared `bfd' and `gdb' libraries built, but + not shared `libg++', you can run all three `configure' scripts as + follows: + + trick$ ./configure --enable-shared=bfd,gdb + + In general, specifying `--enable-shared=PKGS' is the same as + configuring with `--enable-shared' every package named in the + comma-separated PKGS list, and every other package with + `--disable-shared'. The `--enable-static=PKGS' flag behaves + similarly, but it uses `--enable-static' and `--disable-static'. + The same applies to the `--enable-fast-install=PKGS' flag, which + uses `--enable-fast-install' and `--disable-fast-install'. + + The package name `default' matches any packages that have not set + their name in the `PACKAGE' environment variable. + + The `--with-pic' and `--without-pic' configure flags can be used + to specify whether or not `libtool' uses PIC objects. By default, + `libtool' uses PIC objects for shared libraries and non-PIC + objects for static libraries. The `--with-pic' option also + accepts a comma-separated list of package names. Specifying + `--with-pic=PKGS' is the same as configuring every package in PKGS + with `--with-pic' and every other package with the default + configuration. The package name `default' is treated the same as + for `--enable-shared' and `--enable-static'. + + This macro also sets the shell variable `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 `configure.ac': + + LT_INIT + AC_SUBST([LIBTOOL_DEPS]) + + and, to `Makefile.in' or `Makefile.am': + + LIBTOOL_DEPS = @LIBTOOL_DEPS@ + libtool: $(LIBTOOL_DEPS) + $(SHELL) ./config.status libtool + + 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 `libtool'. + + Aside from `disable-static' and `disable-shared', there are other + options that you can pass to `LT_INIT' to modify its behaviour. + Here is a full list: + + `dlopen' + Enable checking for dlopen support. This option should be + used if the package makes use of the `-dlopen' and + `-dlpreopen' libtool flags, otherwise libtool will assume + that the system does not support dlopening. + + `win32-dll' + This option 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 + `__declspec(dllexport)' and imported with + `__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. + + Provision must be made to pass `-no-undefined' to `libtool' + in link mode from the package `Makefile'. Naturally, if you + pass `-no-undefined', you must ensure that all the library + symbols *really are* defined at link time! + + `disable-fast-install' + Change the default behaviour for `LT_INIT' to disable + optimization for fast installation. The user may still + override this default, depending on platform support, by + specifying `--enable-fast-install' to `configure'. + + `shared' + Change the default behaviour for `LT_INIT' to enable shared + libraries. This is the default on all systems where Libtool + knows how to create shared libraries. The user may still + override this default by specifying `--disable-shared' to + `configure'. + + `disable-shared' + Change the default behaviour for `LT_INIT' to disable shared + libraries. The user may still override this default by + specifying `--enable-shared' to `configure'. + + `static' + Change the default behaviour for `LT_INIT' to enable static + libraries. This is the default on all systems where shared + libraries have been disabled for some reason, and on most + systems where shared libraries have been enabled. If shared + libraries are enabled, the user may still override this + default by specifying `--disable-static' to `configure'. + + `disable-static' + Change the default behaviour for `LT_INIT' to disable static + libraries. The user may still override this default by + specifying `--enable-static' to `configure'. + + `pic-only' + Change the default behaviour for `libtool' to try to use only + PIC objects. The user may still override this default by + specifying `--without-pic' to `configure'. + + `no-pic' + Change the default behaviour of `libtool' to try to use only + non-PIC objects. The user may still override this default by + specifying `--with-pic' to `configure'. + + + + -- Macro: LT_LANG (LANGUAGE) + Enable `libtool' support for the language given if it has not yet + already been enabled. Languages accepted are "C++", "Fortran 77", + "Java", "Go", and "Windows Resource". + + If Autoconf language support macros such as `AC_PROG_CXX' are used + in your `configure.ac', Libtool language support will automatically + be enabled. + + Conversely using `LT_LANG' to enable language support for Libtool + will automatically enable Autoconf language support as well. + + Both of the following examples are therefore valid ways of adding + C++ language support to Libtool. + + LT_INIT + LT_LANG([C++]) + + LT_INIT + AC_PROG_CXX + + + -- Macro: AC_LIBTOOL_DLOPEN + This macro is deprecated, the `dlopen' option to `LT_INIT' should + be used instead. + + -- Macro: AC_LIBTOOL_WIN32_DLL + This macro is deprecated, the `win32-dll' option to `LT_INIT' + should be used instead. + + -- Macro: AC_DISABLE_FAST_INSTALL + This macro is deprecated, the `disable-fast-install' option to + `LT_INIT' should be used instead. + + -- Macro: AC_DISABLE_SHARED + -- Macro: AM_DISABLE_SHARED + Change the default behaviour for `LT_INIT' to disable shared + libraries. The user may still override this default by specifying + `--enable-shared'. The option `disable-shared' to `LT_INIT' is a + shorthand for this. `AM_DISABLE_SHARED' is a deprecated alias for + `AC_DISABLE_SHARED'. + + -- Macro: AC_ENABLE_SHARED + -- Macro: AM_ENABLE_SHARED + Change the default behaviour for `LT_INIT' to enable shared + libraries. This is the default on all systems where Libtool knows + how to create shared libraries. The user may still override this + default by specifying `--disable-shared'. The option `shared' to + `LT_INIT' is a shorthand for this. `AM_ENABLE_SHARED' is a + deprecated alias for `AC_ENABLE_SHARED'. + + -- Macro: AC_DISABLE_STATIC + -- Macro: AM_DISABLE_STATIC + Change the default behaviour for `LT_INIT' to disable static + libraries. The user may still override this default by specifying + `--enable-static'. The option `disable-static' to `LT_INIT' is a + shorthand for this. `AM_DISABLE_STATIC' is a deprecated alias for + `AC_DISABLE_STATIC'. + + -- Macro: AC_ENABLE_STATIC + -- Macro: AM_ENABLE_STATIC + Change the default behaviour for `LT_INIT' to enable static + libraries. This is the default on all systems where shared + libraries have been disabled for some reason, and on most systems + where shared libraries have been enabled. If shared libraries are + enabled, the user may still override this default by specifying + `--disable-static'. The option `static' to `LT_INIT' is a + shorthand for this. `AM_ENABLE_STATIC' is a deprecated alias for + `AC_ENABLE_STATIC'. + + The tests in `LT_INIT' also recognize the following environment +variables: + + -- Variable: CC + The C compiler that will be used by the generated `libtool'. If + this is not set, `LT_INIT' will look for `gcc' or `cc'. + + -- Variable: CFLAGS + Compiler flags used to generate standard object files. If this is + not set, `LT_INIT' will not use any such flags. It affects only + the way `LT_INIT' runs tests, not the produced `libtool'. + + -- Variable: CPPFLAGS + C preprocessor flags. If this is not set, `LT_INIT' will not use + any such flags. It affects only the way `LT_INIT' runs tests, not + the produced `libtool'. + + -- Variable: LD + The system linker to use (if the generated `libtool' requires one). + If this is not set, `LT_INIT' will try to find out what is the + linker used by `CC'. + + -- Variable: LDFLAGS + The flags to be used by `libtool' when it links a program. If + this is not set, `LT_INIT' will not use any such flags. It + affects only the way `LT_INIT' runs tests, not the produced + `libtool'. + + -- Variable: LIBS + The libraries to be used by `LT_INIT' when it links a program. If + this is not set, `LT_INIT' will not use any such flags. It + affects only the way `LT_INIT' runs tests, not the produced + `libtool'. + + -- Variable: NM + Program to use rather than checking for `nm'. + + -- Variable: RANLIB + Program to use rather than checking for `ranlib'. + + -- Variable: LN_S + A command that creates a link of a program, a soft-link if + possible, a hard-link otherwise. `LT_INIT' will check for a + suitable program if this variable is not set. + + -- Variable: DLLTOOL + Program to use rather than checking for `dlltool'. Only meaningful + for Cygwin/MS-Windows. + + -- Variable: OBJDUMP + Program to use rather than checking for `objdump'. Only meaningful + for Cygwin/MS-Windows. + + -- Variable: AS + Program to use rather than checking for `as'. Only used on + Cygwin/MS-Windows at the moment. + + -- Variable: MANIFEST_TOOL + Program to use rather than checking for `mt', the Manifest Tool. + Only used on Cygwin/MS-Windows at the moment. + + With 1.3 era libtool, if you wanted to know any details of what +libtool had discovered about your architecture and environment, you had +to run the script with `--config' and grep through the results. This +idiom was supported up to and including 1.5.x era libtool, where it was +possible to call the generated libtool script from `configure.ac' as +soon as `LT_INIT' had completed. However, one of the features of +libtool 1.4 was that the libtool configuration was migrated out of a +separate `ltconfig' file, and added to the `LT_INIT' macro (nee +`AC_PROG_LIBTOOL'), so the results of the configuration tests were +available directly to code in `configure.ac', rendering the call out to +the generated libtool script obsolete. + + Starting with libtool 2.0, the multipass generation of the libtool +script has been consolidated into a single `config.status' pass, which +happens after all the code in `configure.ac' has completed. The +implication of this is that the libtool script does not exist during +execution of code from `configure.ac', and so obviously it cannot be +called for `--config' details anymore. If you are upgrading projects +that used this idiom to libtool 2.0 or newer, you should replace those +calls with direct references to the equivalent Autoconf shell variables +that are set by the configure time tests before being passed to +`config.status' for inclusion in the generated libtool script. + + -- Macro: LT_OUTPUT + By default, the configured `libtool' script is generated by the + call to `AC_OUTPUT' command, and there is rarely any need to use + `libtool' from `configure'. However, sometimes it is necessary to + run configure time compile and link tests using `libtool'. You + can add `LT_OUTPUT' to your `configure.ac' any time after + `LT_INIT' and any `LT_LANG' calls; that done, `libtool' will be + created by a specially generated `config.lt' file, and available + for use in later tests. + + Also, when `LT_OUTPUT' is used, for backwards compatibility with + Automake regeneration rules, `config.status' will call `config.lt' + to regenerate `libtool', rather than generating the file itself. + + When you invoke the `libtoolize' program (*note Invoking +libtoolize::), it will tell you where to find a definition of +`LT_INIT'. If you use Automake, the `aclocal' program will +automatically add `LT_INIT' support to your `configure' script when it +sees the invocation of `LT_INIT' in `configure.ac'. + + Because of these changes, and the runtime version compatibility +checks Libtool now executes, we now advise *against* including a copy of +`libtool.m4' (and brethren) in `acinclude.m4'. Instead, you should set +your project macro directory with `AC_CONFIG_MACRO_DIR'. When you +`libtoolize' your project, a copy of the relevant macro definitions +will be placed in your `AC_CONFIG_MACRO_DIR', where `aclocal' can +reference them directly from `aclocal.m4'. + + ---------- Footnotes ---------- + + (1) `LT_INIT' requires that you define the `Makefile' variable +`top_builddir' in your `Makefile.in'. Automake does this +automatically, but Autoconf users should set it to the relative path to +the top of your build directory (`../..', for example). + + +File: libtool.info, Node: Configure notes, Prev: LT_INIT, Up: Configuring + +5.4.2 Platform-specific configuration notes +------------------------------------------- + +While Libtool tries to hide as many platform-specific features as +possible, some have to be taken into account when configuring either +the Libtool package or a libtoolized package. + + * You currently need GNU make to build the Libtool package itself. + + * On AIX there are two different styles of shared linking, one in + which symbols are bound at link-time and one in which symbols are + bound at runtime only, similar to ELF. In case of doubt use + `LDFLAGS=-Wl,-brtl' for the latter style. + + * On AIX, native tools are to be preferred over binutils; especially + for C++ code, if using the AIX Toolbox GCC 4.0 and binutils, + configure with `AR=/usr/bin/ar LD=/usr/bin/ld NM='/usr/bin/nm -B''. + + * On AIX, the `/bin/sh' is very slow due to its inefficient handling + of here-documents. A modern shell is preferable: + CONFIG_SHELL=/bin/bash; export $CONFIG_SHELL + $CONFIG_SHELL ./configure [...] + + * For C++ code with templates, it may be necessary to specify the + way the compiler will generate the instantiations. For Portland + pgCC version5, use `CXX='pgCC --one_instantiation_per_object'' and + avoid parallel `make'. + + * On Darwin, for C++ code with templates you need two level shared + libraries. Libtool builds these by default if + `MACOSX_DEPLOYMENT_TARGET' is set to 10.3 or later at `configure' + time. See `rdar://problem/4135857' for more information on this + issue. + + * The default shell on UNICOS 9, a ksh 88e variant, is too buggy to + correctly execute the libtool script. Users are advised to + install a modern shell such as GNU bash. + + * Some HP-UX `sed' 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 `sed' (such as + GNU sed) on these systems. + + * The vendor-distributed NCR MP-RAS `cc' programs emits copyright on + standard error that confuse tests on size of `conftest.err'. The + workaround is to specify `CC' when run configure with `CC='cc + -Hnocopyr''. + + * Any earlier DG/UX system with ELF executables, such as R3.10 or + R4.10, is also likely to work, but hasn't been explicitly tested. + + * On Reliant Unix libtool has only been tested with the Siemens + C-compiler and an old version of `gcc' provided by Marco Walther. + + * `libtool.m4', `ltdl.m4' and the `configure.ac' files are marked to + use autoconf-mode, which is distributed with GNU Emacs 21, + Autoconf itself, and all recent releases of XEmacs. + + * When building on some GNU/Linux systems for multilib targets + `libtool' sometimes guesses the wrong paths that the linker and + dynamic linker search by default. If this occurs, you may override + libtool's guesses at `configure' time by setting the `autoconf' + cache variables `lt_cv_sys_lib_search_path_spec' and + `lt_cv_sys_lib_dlsearch_path_spec' respectively to the correct + search paths. + + + +File: libtool.info, Node: Distributing, Next: Static-only libraries, Prev: Configuring, Up: Integrating libtool + +5.5 Including libtool in your package +===================================== + +In order to use libtool, you need to include the following files with +your package: + +`config.guess' + Attempt to guess a canonical system name. + +`config.sub' + Canonical system name validation subroutine script. + +`install-sh' + BSD-compatible `install' replacement script. + +`ltmain.sh' + A generic script implementing basic libtool functionality. + + Note that the libtool script itself should _not_ be included with +your package. *Note Configuring::. + + You should use the `libtoolize' program, rather than manually +copying these files into your package. + +* Menu: + +* Invoking libtoolize:: `libtoolize' command line options. +* Autoconf and LTLIBOBJS:: Autoconf automates LTLIBOBJS generation. + + +File: libtool.info, Node: Invoking libtoolize, Next: Autoconf and LTLIBOBJS, Up: Distributing + +5.5.1 Invoking `libtoolize' +--------------------------- + +The `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 `libtoolize' program has the following synopsis: + + libtoolize [OPTION]... + +and accepts the following options: + +`--copy' +`-c' + Copy files from the libtool data directory rather than creating + symlinks. + +`--debug' + Dump a trace of shell script execution to standard output. This + produces a lot of output, so you may wish to pipe it to `less' (or + `more') or redirect to a file. + +`--dry-run' +`-n' + Don't run any commands that modify the file system, just print them + out. + +`--force' +`-f' + Replace existing libtool files. By default, `libtoolize' won't + overwrite existing files. + +`--help' + Display a help message and exit. + +`--ltdl [TARGET-DIRECTORY-NAME]' + Install libltdl in the TARGET-DIRECTORY-NAME subdirectory of your + package. Normally, the directory is extracted from the argument + to `LT_CONFIG_LTDL_DIR' in `configure.ac', though you can also + specify a subdirectory name here if you are not using Autoconf for + example. If `libtoolize' can't determine the target directory, + `libltdl' is used as the default. + +`--no-warn' + Normally, Libtoolize tries to diagnose use of deprecated libtool + macros and other stylistic issues. If you are deliberately using + outdated calling conventions, this option prevents Libtoolize from + explaining how to update your project's Libtool conventions. + +`--nonrecursive' + If passed in conjunction with `--ltdl', this option will cause the + `libltdl' installed by `libtoolize' to be set up for use with a + non-recursive `automake' build. To make use of it, you will need + to add the following to the `Makefile.am' of the parent project: + + ## libltdl/Makefile.inc appends to the following variables + ## so we set them here before including it: + BUILT_SOURCES = + + AM_CPPFLAGS = + AM_LDFLAGS = + + include_HEADERS = + noinst_LTLIBRARIES = + lib_LTLIBRARIES = + EXTRA_LTLIBRARIES = + + EXTRA_DIST = + + CLEANFILES = + MOSTLYCLEANFILES = + + include libltdl/Makefile.inc + + +`--quiet' +`-q' + Work silently. `libtoolize --quiet' is used by GNU Automake to + add libtool files to your package if necessary. + +`--recursive' + If passed in conjunction with `--ltdl', this option will cause the + `libtoolize' installed `libltdl' to be set up for use with a + recursive `automake' build. To make use of it, you will need to + adjust the parent project's `configure.ac': + + AC_CONFIG_FILES([libltdl/Makefile]) + + and `Makefile.am': + + SUBDIRS += libltdl + +`--subproject' + If passed in conjunction with `--ltdl', this option will cause the + `libtoolize' installed `libltdl' to be set up for independent + configuration and compilation as a self-contained subproject. To + make use of it, you should arrange for your build to call + `libltdl/configure', and then run `make' in the `libltdl' + directory (or the subdirectory you put libltdl into). If your + project uses Autoconf, you can use the supplied `LT_WITH_LTDL' + macro, or else call `AC_CONFIG_SUBDIRS' directly. + + Previous releases of `libltdl' built exclusively in this mode, but + now it is the default mode both for backwards compatibility and + because, for example, it is suitable for use in projects that wish + to use `libltdl', but not use the Autotools for their own build + process. + +`--verbose' +`-v' + Work noisily! Give a blow by blow account of what `libtoolize' is + doing. + +`--version' + Print `libtoolize' version information and exit. + + Sometimes it can be useful to pass options to `libtoolize' even +though it is called by another program, such as `autoreconf'. A +limited number of options are parsed from the environment variable +`LIBTOOLIZE_OPTIONS': currently `--debug', `--no-warn', `--quiet' and +`--verbose'. Multiple options passed in `LIBTOOLIZE_OPTIONS' must be +separated with a space, comma or a colon. + + By default, a warning is issued for unknown options found in +`LIBTOOLIZE_OPTIONS' unless the first such option is `--no-warn'. +Where `libtoolize' has always quit on receipt of an unknown option at +the command line, this and all previous releases of `libtoolize' will +continue unabated whatever the content of `LIBTOOLIZE_OPTIONS' (modulo +some possible warning messages). + + trick$ LIBTOOLIZE_OPTIONS=--no-warn,--quiet autoreconf --install + + If `libtoolize' detects an explicit call to `AC_CONFIG_MACRO_DIR' +(*note The Autoconf Manual: (autoconf)Input.) in your `configure.ac', +it will put the Libtool macros in the specified directory. + + In the future other Autotools will automatically check the contents +of `AC_CONFIG_MACRO_DIR', but at the moment it is more portable to add +the macro directory to `ACLOCAL_AMFLAGS' in `Makefile.am', which is +where the tools currently look. If `libtoolize' doesn't see +`AC_CONFIG_MACRO_DIR', it too will honour the first `-I' argument in +`ACLOCAL_AMFLAGS' when choosing a directory to store libtool +configuration macros in. It is perfectly sensible to use both +`AC_CONFIG_MACRO_DIR' and `ACLOCAL_AMFLAGS', as long as they are kept +in synchronisation. + + ACLOCAL_AMFLAGS = -I m4 + + When you bootstrap your project with `aclocal', then you will need +to explicitly pass the same macro directory with `aclocal''s `-I' flag: + + trick$ aclocal -I m4 + + If `libtoolize' detects an explicit call to `AC_CONFIG_AUX_DIR' +(*note The Autoconf Manual: (autoconf)Input.) in your `configure.ac', it +will put the other support files in the specified directory. Otherwise +they too end up in the project root directory. + + Unless `--no-warn' is passed, `libtoolize' displays hints for adding +libtool support to your package, as well. + + +File: libtool.info, Node: Autoconf and LTLIBOBJS, Prev: Invoking libtoolize, Up: Distributing + +5.5.2 Autoconf and `LTLIBOBJS' +------------------------------ + +People used to add code like the following to their `configure.ac': + + LTLIBOBJS=`echo "$LIBOBJS" | sed 's/\.[^.]* /.lo /g;s/\.[^.]*$/.lo/'` + AC_SUBST([LTLIBOBJS]) + +This is no longer required (since Autoconf 2.54), and doesn't take +Automake's deansification support into account either, so doesn't work +correctly even with ancient Autoconfs! + + Provided you are using a recent (2.54 or better) incarnation of +Autoconf, the call to `AC_OUTPUT' takes care of setting `LTLIBOBJS' up +correctly, so you can simply delete such snippets from your +`configure.ac' if you had them. + + +File: libtool.info, Node: Static-only libraries, Prev: Distributing, Up: Integrating libtool + +5.6 Static-only libraries +========================= + +When you are developing a package, it is often worthwhile to configure +your package with the `--disable-shared' flag, or to override the +defaults for `LT_INIT' by using the `disable-shared' option (*note The +`LT_INIT' macro: LT_INIT.). This prevents libtool from building shared +libraries, which has several advantages: + + * compilation is twice as fast, which can speed up your development + cycle, + + * debugging is easier because you don't need to deal with any + complexities added by shared libraries, and + + * you can see how libtool behaves on static-only platforms. + + You may want to put a small note in your package `README' to let +other developers know that `--disable-shared' can save them time. The +following example note is taken from the GIMP(1) distribution `README': + + 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 `--disable-shared' option to `configure'. + + ---------- Footnotes ---------- + + (1) GNU Image Manipulation Program, for those who haven't taken the +plunge. See `http://www.gimp.org/'. + + +File: libtool.info, Node: Other languages, Next: Versioning, Prev: Integrating libtool, Up: Top + +6 Using libtool with other languages +************************************ + +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: + +* C++ libraries:: Writing libraries for C++ +* Tags:: Tags + + +File: libtool.info, Node: C++ libraries, Next: Tags, Up: Other languages + +6.1 Writing libraries for C++ +============================= + +Creating libraries of C++ code should be a fairly straightforward +process, because its object files differ from C ones in only three ways: + + 1. 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. + + 2. 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 `ld' directly to link such + libraries, and we should use the C++ compiler instead. + + 3. 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 `ld' to link a C++ program or + library is deemed to fail. + + Because of these three issues, Libtool has been designed to always +use the C++ compiler to compile and link C++ programs and libraries. In +some instances the `main()' function of a program must also be compiled +with the C++ compiler for static C++ objects to be properly initialized. + + +File: libtool.info, Node: Tags, Prev: C++ libraries, Up: Other languages + +6.2 Tags +======== + +Libtool supports multiple languages through the use of tags. +Technically a tag corresponds to a set of configuration variables +associated with a language. These variables tell `libtool' how it +should create objects and libraries for each language. + + Tags are defined at `configure'-time for each language activated in +the package (see `LT_LANG' in *note LT_INIT::). Here is the +correspondence between language names and tags names. + +Language name Tag name +C CC +C++ CXX +Java GCJ +Fortran 77 F77 +Fortran FC +Go GO +Windows Resource RC + + `libtool' tries to automatically infer which tag to use from the +compiler command being used to compile or link. If it can't infer a +tag, then it defaults to the configuration for the `C' language. + + The tag can also be specified using `libtool''s `--tag=TAG' option +(*note Invoking libtool::). It is a good idea to do so in `Makefile' +rules, because that will allow users to substitute the compiler without +relying on `libtool' inference heuristics. When no tag is specified, +`libtool' will default to `CC'; this tag always exists. + + Finally, the set of tags available in a particular project can be +retrieved by tracing for the `LT_SUPPORTED_TAG' macro (*note Trace +interface::). + + +File: libtool.info, Node: Versioning, Next: Library tips, Prev: Other languages, Up: Top + +7 Library interface 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 +`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. + + +File: libtool.info, Node: Interfaces, Next: Libtool versioning, Up: Versioning + +7.1 What are library interfaces? +================================ + +Interfaces for libraries may be any of the following (and more): + + * global variables: both names and types + + * global functions: argument types and number, return types, and + function names + + * standard input, standard output, standard error, and file formats + + * sockets, pipes, and other inter-process communication protocol + formats + + Note that static functions do not count as interfaces, because they +are not directly available to the user of the library. + + +File: libtool.info, Node: Libtool versioning, Next: Updating version info, Prev: Interfaces, Up: Versioning + +7.2 Libtool's versioning system +=============================== + +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 (FIRST-INTERFACE, LAST-INTERFACE). + + The dynamic linker is guaranteed that if a library supports _every_ +interface number between FIRST-INTERFACE and 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 `libhello' supports interfaces 5, 16, 17, 18, and 19, and that +libtool is used to link `test' against `libhello'. + + Libtool encodes the numbers 5 and 19 in `test', and the dynamic +linker will only link `test' against libraries that support _every_ +interface between 5 and 19. So, the dynamic linker refuses to link +`test' against `libhello'! + + In order to eliminate this problem, libtool only allows libraries to +declare consecutive interface numbers. So, `libhello' can declare at +most that it supports interfaces 16 through 19. Then, the dynamic +linker will link `test' against `libhello'. + + So, libtool library versions are described by three integers: + +CURRENT + The most recent interface number that this library implements. + +REVISION + The implementation number of the CURRENT interface. + +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 `CURRENT - AGE' to + `CURRENT'. + + If two libraries have identical CURRENT and AGE numbers, then the +dynamic linker chooses the library with the greater REVISION number. + + +File: libtool.info, Node: Updating version info, Next: Release numbers, Prev: Libtool versioning, Up: Versioning + +7.3 Updating library version information +======================================== + +If you want to use libtool's versioning system, then you must specify +the version information to libtool using the `-version-info' flag +during link mode (*note Link mode::). + + This flag accepts an argument of the form +`CURRENT[:REVISION[:AGE]]'. So, passing `-version-info 3:12:1' sets +CURRENT to 3, REVISION to 12, and AGE to 1. + + If either REVISION or AGE are omitted, they default to 0. Also note +that AGE must be less than or equal to the CURRENT interface number. + + Here are a set of rules to help you update your library version +information: + + 1. Start with version information of `0:0:0' for each libtool library. + + 2. 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. + + 3. If the library source code has changed at all since the last + update, then increment REVISION (`C:R:A' becomes `C:r+1:A'). + + 4. If any interfaces have been added, removed, or changed since the + last update, increment CURRENT, and set REVISION to 0. + + 5. If any interfaces have been added since the last public release, + then increment AGE. + + 6. If any interfaces have been removed or changed since the last + public release, then set AGE to 0. + + *_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 `-release' flag (*note Release numbers::), but be warned that +every release of your package will not be binary compatible with any +other release. + + The following explanation may help to understand the above rules a +bit better: consider that there are three possible kinds of reactions +from users of your library to changes in a shared library: + + 1. Programs using the previous version may use the new version as + drop-in replacement, and programs using the new version can also + work with the previous one. In other words, no recompiling nor + relinking is needed. In this case, bump REVISION only, don't touch + CURRENT nor AGE. + + 2. Programs using the previous version may use the new version as + drop-in replacement, but programs using the new version may use + APIs not present in the previous one. In other words, a program + linking against the new version may fail with "unresolved symbols" + if linking against the old version at runtime: set REVISION to 0, + bump CURRENT and AGE. + + 3. Programs may need to be changed, recompiled, relinked in order to + use the new version. Bump CURRENT, set REVISION and AGE to 0. + +In the above description, _programs_ using the library in question may +also be replaced by other libraries using it. + + +File: libtool.info, Node: Release numbers, Prev: Updating version info, Up: Versioning + +7.4 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: + + trick$ ls /usr/lib/libbfd* + /usr/lib/libbfd.a /usr/lib/libbfd.so.2.7.0.2 + /usr/lib/libbfd.so + trick$ + + On `trick', `/usr/lib/libbfd.so' is a symbolic link to +`libbfd.so.2.7.0.2', which was distributed as a part of +`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 `-release' +flag in order to set release information for libraries for which you do +not want to use `-version-info'. For the `libbfd' example, the next +release that uses libtool should be built with `-release 2.9.0', which +will produce the following files on GNU/Linux: + + trick$ ls /usr/lib/libbfd* + /usr/lib/libbfd-2.9.0.so /usr/lib/libbfd.a + /usr/lib/libbfd.so + trick$ + + In this case, `/usr/lib/libbfd.so' is a symbolic link to +`libbfd-2.9.0.so'. This makes it obvious that the user is dealing with +`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 `-release' for +package-internal libraries or for ones whose interfaces change very +frequently. + + +File: libtool.info, Node: Library tips, Next: Inter-library dependencies, Prev: Versioning, Up: Top + +8 Tips for interface design +*************************** + +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 that may +help you in your exploits: + +Plan ahead + Try to make every interface truly minimal, so that you won't need + to delete entry points very often. + +Avoid interface changes + Some people love redesigning and changing entry points just for + the heck of it (note: _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. + +Use 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 (that 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. + +Use 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 (*note C header files::). + +Use the `static' keyword (or equivalent) whenever possible + 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... your users cannot access + them, so they aren't interface changes. + +Be careful with array dimensions + The number of elements in a global array is part of an interface, + even if the header just declares `extern int foo[];'. This is + because on i386 and some other SVR4/ELF systems, when an + application references data in a shared library the size of that + data (whatever its type) is included in the application + executable. If you might want to change the size of an array or + string then provide a pointer not the actual array. + +* Menu: + +* C header files:: How to write portable include files. + + +File: libtool.info, Node: C header files, Up: Library tips + +8.1 Writing C header files +========================== + +Writing portable C header files can be difficult, since they may be read +by different types of compilers: + +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 `extern "C"' + directive, so that the names aren't mangled. *Note C++ + libraries::, for other issues relevant to using C++ with libtool. + +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 `#include'd. + +non-ANSI C compilers + Non-ANSI compilers will report errors if functions are prototyped. + + 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. + + `foo.h' in the `tests/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: + + /* BEGIN_C_DECLS should be used at the beginning of your declarations, + so that C++ compilers don't mangle their names. Use END_C_DECLS at + the end of C declarations. */ + #undef BEGIN_C_DECLS + #undef END_C_DECLS + #ifdef __cplusplus + # define BEGIN_C_DECLS extern "C" { + # define END_C_DECLS } + #else + # define BEGIN_C_DECLS /* empty */ + # define END_C_DECLS /* empty */ + #endif + + /* PARAMS 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 PARAMS + #if defined (__STDC__) || defined (_AIX) \ + || (defined (__mips) && defined (_SYSTYPE_SVR4)) \ + || defined(WIN32) || defined(__cplusplus) + # define PARAMS(protos) protos + #else + # define PARAMS(protos) () + #endif + + These macros are used in `foo.h' as follows: + + #ifndef FOO_H + #define FOO_H 1 + + /* The above macro definitions. */ + #include "..." + + BEGIN_C_DECLS + + int foo PARAMS((void)); + int hello PARAMS((void)); + + END_C_DECLS + + #endif /* !FOO_H */ + + Note that the `#ifndef FOO_H' prevents the body of `foo.h' from +being read more than once in a given compilation. + + Also the only thing that must go outside the +`BEGIN_C_DECLS'/`END_C_DECLS' pair are `#include' lines. Strictly +speaking it is only C symbol names that need to be protected, but your +header files will be more maintainable if you have a single pair of +these macros around the majority of the header contents. + + You should use these definitions of `PARAMS', `BEGIN_C_DECLS', and +`END_C_DECLS' into your own headers. Then, you may use them to create +header files that are valid for C++, ANSI, and non-ANSI compilers(1). + + 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: + + * Pre-ANSI compilers do not always support the `void *' generic + pointer type, and so need to use `char *' in its place. + + * The `const', `inline' and `signed' keywords are not supported by + some compilers, especially pre-ANSI compilers. + + * The `long double' type is not supported by many compilers. + + ---------- Footnotes ---------- + + (1) We used to recommend `__P', `__BEGIN_DECLS' and `__END_DECLS'. +This was bad advice since symbols (even preprocessor macro names) that +begin with an underscore are reserved for the use of the compiler. + + +File: libtool.info, Node: Inter-library dependencies, Next: Dlopened modules, Prev: Library tips, Up: Top + +9 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 "inter-library dependency" is one in which a library depends on +other libraries. For example, if the libtool library `libhello' uses +the `cos' function, then it has an inter-library dependency on `libm', +the math library that implements `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 `libNAME' that your own +library depends on, simply add a corresponding `-lNAME' option to the +link line when you create your library. To make an example of our +`libhello' that depends on `libm': + + burger$ libtool --mode=link gcc -g -O -o libhello.la foo.lo hello.lo \ + -rpath /usr/local/lib -lm + burger$ + + When you link a program against `libhello', you don't need to +specify the same `-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 Windows, do not even allow you this +flexibility. In order to build a shared library, it must be entirely +self-contained or it must have dependencies known at link time (that is, +have references only to symbols that are found in the `.lo' files or +the specified `-l' libraries), and you need to specify the +`-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. + + +File: libtool.info, Node: Dlopened modules, Next: Using libltdl, Prev: Inter-library dependencies, Up: Top + +10 Dlopened modules +******************* + +It can sometimes be confusing to discuss "dynamic linking", because the +term is used to refer to two different concepts: + + 1. 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. + + 2. The application calling functions such as `dlopen' that load + arbitrary, user-specified modules at runtime. This type of dynamic + linking is explicitly controlled by the application. + + To mitigate confusion, this manual refers to the second type of +dynamic linking as "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. + + Libtool provides support for dlopened modules. However, you should +indicate that your package is willing to use such support, by using the +`LT_INIT' option `dlopen' in `configure.ac'. If this option is not +given, 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. +* Linking with dlopened modules:: Using dlopenable modules in libraries. +* Finding the dlname:: Choosing the right file to `dlopen'. +* Dlopen issues:: Unresolved problems that need your attention. + + +File: libtool.info, Node: Building modules, Next: Dlpreopening, Up: Dlopened modules + +10.1 Building modules to dlopen +=============================== + +On some operating systems, a program symbol must be specially declared +in order to be dynamically resolved with the `dlsym' (or equivalent) +function. Libtool provides the `-export-dynamic' and `-module' link +flags (*note Link mode::), for you to make that 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, `hello', that +would later be dlopened by an application, we would add `-module' to +the other link flags: + + burger$ libtool --mode=link gcc -module -o hello.la foo.lo \ + hello.lo -rpath /usr/local/lib -lm + burger$ + + If symbols from your _executable_ are needed to satisfy unresolved +references in a library you want to dlopen you will have to use the flag +`-export-dynamic'. You should use `-export-dynamic' while linking the +executable that calls dlopen: + + burger$ libtool --mode=link gcc -export-dynamic -o helldl main.o + burger$ + + +File: libtool.info, Node: Dlpreopening, Next: Linking with dlopened modules, Prev: Building modules, Up: Dlopened modules + +10.2 Dlpreopening +================= + +Libtool provides special support for dlopening libtool object and +libtool library files, so that their symbols can be resolved _even on +platforms without any `dlopen' and `dlsym' functions_. + + Consider the following alternative ways of loading code into your +program, in order of increasing "laziness": + + 1. 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 compile time linker refuses to create + the executable. + + 2. 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 compile time linker refuses to create the executable. + + 3. 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. + + 4. 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. + + Libtool emulates `-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 `-dlopen' or `-dlpreopen' flags when you link your program +(*note Link mode::). + + -- Data Type: lt_dlsymlist typedef struct { const char *NAME; + void *ADDRESS; } lt_dlsymlist + The NAME attribute is a null-terminated character string of the + symbol name, such as `"fprintf"'. The ADDRESS attribute is a + generic pointer to the appropriate object, such as `&fprintf'. + + -- Variable: const lt_dlsymlist lt_preloaded_symbols[] + An array of `lt_dlsymlist' structures, representing all the + preloaded symbols linked into the program proper. For each module + `-dlpreopen'ed by the Libtool linked program there is an element + with the NAME of the module and an ADDRESS of `0', followed by all + symbols exported from this file. For the executable itself the + special name `@PROGRAM@' is used. The last element of all has a + NAME and ADDRESS of `0'. + + To facilitate inclusion of symbol lists into libraries, + `lt_preloaded_symbols' is `#define'd to a suitably unique name in + `ltdl.h'. + + This variable may not be declared `const' on some systems due to + relocation issues. + + Some compilers may allow identifiers that 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 `lt_preloaded_symbols'. + + -- Function: int lt_dlpreload (const lt_dlsymlist *PRELOADED) + Register the list of preloaded modules PRELOADED. If PRELOADED is + `NULL', then all previously registered symbol lists, except the + list set by `lt_dlpreload_default', are deleted. Return 0 on + success. + + -- Function: int lt_dlpreload_default (const lt_dlsymlist *PRELOADED) + Set the default list of preloaded modules to PRELOADED, which + won't be deleted by `lt_dlpreload'. Note that this function does + _not_ require libltdl to be initialized using `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 `LTDL_SET_PRELOADED_SYMBOLS'. + + Return 0 on success. + + -- Macro: 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. + + #include + + int main() { + /* ... */ + LTDL_SET_PRELOADED_SYMBOLS(); + /* ... */ + } + + -- Function Type: int lt_dlpreload_callback_func (lt_dlhandle HANDLE) + Functions of this type can be passed to `lt_dlpreload_open', which + in turn will call back into a function thus passed for each + preloaded module that it opens. + + -- Function: int lt_dlpreload_open (const char *ORIGINATOR, + lt_dlpreload_callback_func *FUNC) + Load all of the preloaded modules for ORIGINATOR. For every + module opened in this way, call FUNC. + + To open all of the modules preloaded into `libhell.la' (presumably + from within the `libhell.a' initialisation code): + + #define preloaded_symbols lt_libhell_LTX_preloaded_symbols + + static int hell_preload_callback (lt_dlhandle handle); + + int + hell_init (void) + { + ... + if (lt_dlpreload (&preloaded_symbols) == 0) + { + lt_dlpreload_open ("libhell", preload_callback); + } + ... + } + + Note that to prevent clashes between multiple preloaded modules, + the preloaded symbols are accessed via a mangled symbol name: to + get the symbols preloaded into `libhell', you must prefix + `preloaded_symbols' with `lt_'; the originator name, `libhell' in + this case; and `_LTX_'. That is, + `lt_libhell_LTX_preloaded_symbols' here. + + +File: libtool.info, Node: Linking with dlopened modules, Next: Finding the dlname, Prev: Dlpreopening, Up: Dlopened modules + +10.3 Linking with dlopened modules +================================== + +When, say, an interpreter application uses dlopened modules to extend +the list of methods it provides, an obvious abstraction for the +maintainers of the interpreter is to have all methods (including the +built in ones supplied with the interpreter) accessed through dlopen. +For one thing, the dlopening functionality will be tested even during +routine invocations. For another, only one subsystem has to be written +for getting methods into the interpreter. + + The downside of this abstraction is, of course, that environments +that provide only static linkage can't even load the intrinsic +interpreter methods. Not so! We can statically link those methods by +*dlpreopening* them. + + Unfortunately, since platforms such as AIX and cygwin require that +all library symbols must be resolved at compile time, the interpreter +maintainers will need to provide a library to both its own dlpreopened +modules, and third-party modules loaded by dlopen. In itself, that is +not so bad, except that the interpreter too must provide those same +symbols otherwise it will be impossible to resolve all the symbols +required by the modules as they are loaded. Things are even worse if +the code that loads the modules for the interpreter is itself in a +library - and that is usually the case for any non-trivial application. +Modern platforms take care of this by automatically loading all of a +module's dependency libraries as the module is loaded (libltdl can do +this even on platforms that can't do it by themselves). In the end, +this leads to problems with duplicated symbols and prevents modules +from loading, and prevents the application from compiling when modules +are preloaded. + + ,-------------. ,------------------. ,-----------------. + | Interpreter |----> Module------------> Third-party | + `-------------' | Loader | |Dlopened Modules | + | | | `-----------------' + |,-------v--------.| | + || Dlpreopened || | + || Modules || | + |`----------------'| | + | | | | + |,-------v--------.| ,--------v--------. + ||Module Interface|| |Module Interface | + || Library || | Library | + |`----------------'| `-----------------' + `------------------' + + Libtool has the concept of "weak library interfaces" to circumvent +this problem. Recall that the code that dlopens method-provider +modules for the interpreter application resides in a library: All of +the modules and the dlopener library itself should be linked against +the common library that resolves the module symbols at compile time. +To guard against duplicate symbol definitions, and for dlpreopened +modules to work at all in this scenario, the dlopener library must +declare that it provides a weak library interface to the common symbols +in the library it shares with the modules. That way, when `libtool' +links the *Module Loader* library with some *Dlpreopened Modules* that +were in turn linked against the *Module Interface Library*, it knows +that the *Module Loader* provides an already loaded *Module Interface +Library* to resolve symbols for the *Dlpreopened Modules*, and doesn't +ask the compiler driver to link an identical *Module Interface Library* +dependency library too. + + In conjunction with Automake, the `Makefile.am' for the *Module +Loader* might look like this: + + lib_LTLIBRARIES = libinterface.la libloader.la + + libinterface_la_SOURCES = interface.c interface.h + libinterface_la_LDFLAGS = -version-info 3:2:1 + + libloader_la_SOURCES = loader.c + libloader_la_LDFLAGS = -weak libinterface.la \ + -version-info 3:2:1 \ + -dlpreopen ../modules/intrinsics.la + libloader_la_LIBADD = $(libinterface_la_OBJECTS) + + And the `Makefile.am' for the `intrinsics.la' module in a sibling +`modules' directory might look like this: + + AM_CPPFLAGS = -I$(srcdir)/../libloader + AM_LDFLAGS = -no-undefined -module -avoid-version \ + -export-dynamic + + noinst_LTLIBRARIES = intrinsics.la + + intrinsics_la_LIBADD = ../libloader/libinterface.la + + ../libloader/libinterface.la: + cd ../libloader && $(MAKE) $(AM_MAKEFLAGS) libinterface.la + + For a more complex example, see the sources of `libltdl' in the +Libtool distribution, which is built with the help of the `-weak' +option. + + +File: libtool.info, Node: Finding the dlname, Next: Dlopen issues, Prev: Linking with dlopened modules, Up: Dlopened modules + +10.4 Finding the correct name to dlopen +======================================= + +After a library has been linked with `-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 `.la' file, and searching +it for the following lines: + + # The name that we can `dlopen'. + dlname='DLNAME' + + If DLNAME is empty, then the library cannot be dlopened. Otherwise, +it gives the dlname of the library. So, if the library was installed +as `/usr/local/lib/libhello.la', and the DLNAME was `libhello.so.3', +then `/usr/local/lib/libhello.so.3' should be dlopened. + + If your program uses this approach, then it should search the +directories listed in the `LD_LIBRARY_PATH'(1) 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. + + ---------- Footnotes ---------- + + (1) `LIBPATH' on AIX, and `SHLIB_PATH' on HP-UX. + + +File: libtool.info, Node: Dlopen issues, Prev: Finding the dlname, Up: Dlopened modules + +10.5 Unresolved dlopen issues +============================= + +The following problems are not solved by using libtool's dlopen support: + + * 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 (*note Using libltdl::) + or develop your own alternatives to dlopening dynamic code. Most + reasonable solutions involve writing wrapper functions for the + `dlopen' family, which do package-specific tricks when dlopening + is unsupported or not available on a given platform. + + * There are major differences in implementations of the `dlopen' + family of functions. Some platforms do not even use the same + function names (notably HP-UX, with its `shl_load' family). + + * The application developer must write a custom search function in + order to discover the correct module filename to supply to + `dlopen'. + + +File: libtool.info, Node: Using libltdl, Next: Trace interface, Prev: Dlopened modules, Up: Top + +11 Using libltdl +**************** + +Libtool provides a small library, called `libltdl', that aims at hiding +the various difficulties of dlopening libraries from programmers. It +consists of a few headers and small C source files that can be +distributed with applications that need dlopening functionality. On +some platforms, whose dynamic linkers are too limited for a simple +implementation of `libltdl' services, it requires GNU DLD, or it will +only emulate dynamic linking with libtool's dlpreopening mechanism. + +libltdl supports currently the following dynamic linking mechanisms: + + * `dlopen' (POSIX compliant systems, GNU/Linux, etc.) + + * `shl_load' (HP-UX) + + * `LoadLibrary' (Win16 and Win32) + + * `load_add_on' (BeOS) + + * `NSAddImage' or `NSLinkModule' (Darwin and Mac OS X) + + * GNU DLD (emulates dynamic linking for static libraries) + + * libtool's dlpreopen (see *note Dlpreopening::) + +libltdl is licensed under the terms of the GNU Lesser General Public +License, with the following exception: + + As a special exception to the GNU Lesser General Public License, + if you distribute this file as part of a program or library that + is built using GNU Libtool, you may include it under the same + distribution terms that you use for the rest of that program. + +* Menu: + +* Libltdl interface:: How to use libltdl in your programs. +* Modules for libltdl:: Creating modules that can be `dlopen'ed. +* Thread Safety in libltdl:: Registering callbacks for multi-thread safety. +* User defined module data:: Associating data with loaded modules. +* Module loaders for libltdl:: Creating user defined module loaders. +* Distributing libltdl:: How to distribute libltdl with your package. + + +File: libtool.info, Node: Libltdl interface, Next: Modules for libltdl, Up: Using libltdl + +11.1 How to use libltdl in your programs +======================================== + +The libltdl API is similar to the POSIX dlopen interface, which is very +simple but powerful. + +To use libltdl in your program you have to include the header file +`ltdl.h': + + #include + +The early releases of libltdl used some symbols that violated the POSIX +namespace conventions. These symbols are now deprecated, and have been +replaced by those described here. If you have code that relies on the +old deprecated symbol names, defining `LT_NON_POSIX_NAMESPACE' before +you include `ltdl.h' provides conversion macros. Whichever set of +symbols you use, the new API is not binary compatible with the last, so +you will need to recompile your application in order to use this +version of libltdl. + +Note that libltdl is not well tested in a multithreaded environment, +though the intention is that it should work (*note Using libltdl in a +multi threaded environment: Thread Safety in libltdl.). It was +reported that GNU/Linux's glibc 2.0's `dlopen' with `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, `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. + +The following macros are defined by including `ltdl.h': + + -- Macro: LT_PATHSEP_CHAR + `LT_PATHSEP_CHAR' is the system-dependent path separator, that is, + `;' on Windows and `:' everywhere else. + + -- Macro: LT_DIRSEP_CHAR + If `LT_DIRSEP_CHAR' is defined, it can be used as directory + separator in addition to `/'. On Windows, this contains `\'. + +The following types are defined in `ltdl.h': + + -- Type: lt_dlhandle + `lt_dlhandle' is a module "handle". Every lt_dlopened module has + a handle associated with it. + + -- Type: lt_dladvise + `lt_dladvise' is used to control optional module loading modes. + If it is not used, the default mode of the underlying system module + loader is used. + + -- Type: lt_dlsymlist + `lt_dlsymlist' is a symbol list for dlpreopened modules. This + structure is described in *note Dlpreopening::. + +libltdl provides the following functions: + + -- Function: 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. + + -- Function: 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 + `lt_dlinit' has been successfully called. Return 0 on success, + otherwise the number of errors. + + -- Function: lt_dlhandle lt_dlopen (const char *FILENAME) + Open the module with the file name FILENAME and return a handle + for it. `lt_dlopen' is able to open libtool dynamic modules, + preloaded static modules, the program itself and native dynamic + modules(1). + + Unresolved symbols in the module are resolved using its dependency + libraries and previously dlopened modules. If the executable using + this module was linked with the `-export-dynamic' flag, then the + global symbols in the executable will also be used to resolve + references in the module. + + If FILENAME is `NULL' and the program was linked with + `-export-dynamic' or `-dlopen self', `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 FILENAME does + not have a directory component it will additionally look in the + following search paths for the module (in the following order): + + 1. user-defined search path: This search path can be changed by + the program using the functions `lt_dlsetsearchpath', + `lt_dladdsearchdir' and `lt_dlinsertsearchdir'. + + 2. libltdl's search path: This search path is the value of the + environment variable `LTDL_LIBRARY_PATH'. + + 3. system library search path: The system dependent library + search path (e.g. on GNU/Linux it is `LD_LIBRARY_PATH'). + + Each search path must be a list of absolute directories separated + by `LT_PATHSEP_CHAR', for example, `"/usr/lib/mypkg:/lib/foo"'. + The directory names may not contain the path separator. + + If the same module is loaded several times, the same handle is + returned. If `lt_dlopen' fails for any reason, it returns `NULL'. + + -- Function: lt_dlhandle lt_dlopenext (const char *FILENAME) + The same as `lt_dlopen', except that it tries to append different + file name extensions to the file name. If the file with the file + name FILENAME cannot be found libltdl tries to append the + following extensions: + + 1. the libtool archive extension `.la' + + 2. the extension used for native dynamically loadable modules on + the host platform, e.g., `.so', `.sl', etc. + + This lookup strategy was designed to allow programs that don't + have knowledge about native dynamic libraries naming conventions + to be able to `dlopen' such libraries as well as libtool modules + transparently. + + -- Function: lt_dlhandle lt_dlopenadvise (const char *FILENAME, + lt_dladvise ADVISE) + The same as `lt_dlopen', except that it also requires an additional + argument which may contain additional hints to the underlying + system module loader. The ADVISE parameter is opaque and can only + be accessed with the functions documented below. + + Note that this function does not change the content of ADVISE, so + unlike the other calls in this API takes a direct `lt_dladvise' + type, and not a pointer to the same. + + -- Function: int lt_dladvise_init (lt_dladvise *ADVISE) + The ADVISE parameter can be used to pass hints to the module + loader when using `lt_dlopenadvise' to perform the loading. The + ADVISE parameter needs to be initialised by this function before + it can be used. Any memory used by ADVISE needs to be recycled + with `lt_dladvise_destroy' when it is no longer needed. + + On failure, `lt_dladvise_init' returns non-zero and sets an error + message that can be retrieved with `lt_dlerror'. + + -- Function: int lt_dladvise_destroy (lt_dladvise *ADVISE) + Recycle the memory used by ADVISE. For an example, see the + documentation for `lt_dladvise_ext'. + + On failure, `lt_dladvise_destroy' returns non-zero and sets an + error message that can be retrieved with `lt_dlerror'. + + -- Function: int lt_dladvise_ext (lt_dladvise *ADVISE) + Set the `ext' hint on ADVISE. Passing an ADVISE parameter to + `lt_dlopenadvise' with this hint set causes it to try to append + different file name extensions like `lt_dlopenext'. + + The following example is equivalent to calling `lt_dlopenext + (filename)': + + lt_dlhandle + my_dlopenext (const char *filename) + { + lt_dlhandle handle = 0; + lt_dladvise advise; + + if (!lt_dladvise_init (&advise) && !lt_dladvise_ext (&advise)) + handle = lt_dlopenadvise (filename, advise); + + lt_dladvise_destroy (&advise); + + return handle; + } + + On failure, `lt_dladvise_ext' returns non-zero and sets an error + message that can be retrieved with `lt_dlerror'. + + -- Function: int lt_dladvise_global (lt_dladvise *ADVISE) + Set the `symglobal' hint on ADVISE. Passing an ADVISE parameter + to `lt_dlopenadvise' with this hint set causes it to try to make + the loaded module's symbols globally available for resolving + unresolved symbols in subsequently loaded modules. + + If neither the `symglobal' nor the `symlocal' hints are set, or if + a module is loaded without using the `lt_dlopenadvise' call in any + case, then the visibility of the module's symbols will be as per + the default for the underlying module loader and OS. Even if a + suitable hint is passed, not all loaders are able to act upon it in + which case `lt_dlgetinfo' will reveal whether the hint was actually + followed. + + On failure, `lt_dladvise_global' returns non-zero and sets an error + message that can be retrieved with `lt_dlerror'. + + -- Function: int lt_dladvise_local (lt_dladvise *ADVISE) + Set the `symlocal' hint on ADVISE. Passing an ADVISE parameter to + `lt_dlopenadvise' with this hint set causes it to try to keep the + loaded module's symbols hidden so that they are not visible to + subsequently loaded modules. + + If neither the `symglobal' nor the `symlocal' hints are set, or if + a module is loaded without using the `lt_dlopenadvise' call in any + case, then the visibility of the module's symbols will be as per + the default for the underlying module loader and OS. Even if a + suitable hint is passed, not all loaders are able to act upon it in + which case `lt_dlgetinfo' will reveal whether the hint was actually + followed. + + On failure, `lt_dladvise_local' returns non-zero and sets an error + message that can be retrieved with `lt_dlerror'. + + -- Function: int lt_dladvise_resident (lt_dladvise *ADVISE) + Set the `resident' hint on ADVISE. Passing an ADVISE parameter to + `lt_dlopenadvise' with this hint set causes it to try to make the + loaded module resident in memory, so that it cannot be unloaded + with a later call to `lt_dlclose'. + + On failure, `lt_dladvise_resident' returns non-zero and sets an + error message that can be retrieved with `lt_dlerror'. + + -- Function: int lt_dladvise_preload (lt_dladvise *ADVISE) + Set the `preload' hint on ADVISE. Passing an ADVISE parameter to + `lt_dlopenadvise' with this hint set causes it to load only + preloaded modules, so that if a suitable preloaded module is not + found, `lt_dlopenadvise' will return `NULL'. + + -- Function: int lt_dlclose (lt_dlhandle HANDLE) + Decrement the reference count on the module HANDLE. If it drops + to zero and no other module depends on this module, then the + module is unloaded. Return 0 on success. + + -- Function: void * lt_dlsym (lt_dlhandle HANDLE, const char *NAME) + Return the address in the module HANDLE, where the symbol given by + the null-terminated string NAME is loaded. If the symbol cannot + be found, `NULL' is returned. + + -- Function: const char * lt_dlerror (void) + Return a human readable string describing the most recent error + that occurred from any of libltdl's functions. Return `NULL' if + no errors have occurred since initialization or since it was last + called. + + -- Function: int lt_dladdsearchdir (const char *SEARCH_DIR) + Append the search directory SEARCH_DIR to the current user-defined + library search path. Return 0 on success. + + -- Function: int lt_dlinsertsearchdir (const char *BEFORE, + const char *SEARCH_DIR) + Insert the search directory SEARCH_DIR into the user-defined + library search path, immediately before the element starting at + address BEFORE. If BEFORE is `NULL', then SEARCH_DIR is appending + as if `lt_dladdsearchdir' had been called. Return 0 on success. + + -- Function: int lt_dlsetsearchpath (const char *SEARCH_PATH) + Replace the current user-defined library search path with + SEARCH_PATH, which must be a list of absolute directories separated + by `LT_PATHSEP_CHAR'. Return 0 on success. + + -- Function: const char * lt_dlgetsearchpath (void) + Return the current user-defined library search path. + + -- Function: int lt_dlforeachfile (const char *SEARCH_PATH, + int (*FUNC) (const char *FILENAME, void * DATA), void * DATA) + In some applications you may not want to load individual modules + with known names, but rather find all of the modules in a set of + directories and load them all during initialisation. With this + function you can have libltdl scan the `LT_PATHSEP_CHAR'-delimited + directory list in SEARCH_PATH for candidates, and pass them, along + with DATA to your own callback function, FUNC. If SEARCH_PATH is + `NULL', then search all of the standard locations that `lt_dlopen' + would examine. This function will continue to make calls to FUNC + for each file that it discovers in SEARCH_PATH until one of these + calls returns non-zero, or until the files are exhausted. + `lt_dlforeachfile' returns the value returned by the last call + made to FUNC. + + For example you could define FUNC to build an ordered "argv"-like + vector of files using DATA to hold the address of the start of the + vector. + + -- Function: int lt_dlmakeresident (lt_dlhandle HANDLE) + Mark a module so that it cannot be `lt_dlclose'd. This can be + useful if a module implements some core functionality in your + project that would cause your code to crash if removed. Return 0 + on success. + + If you use `lt_dlopen (NULL)' to get a HANDLE for the running + binary, that handle will always be marked as resident, and + consequently cannot be successfully `lt_dlclose'd. + + -- Function: int lt_dlisresident (lt_dlhandle HANDLE) + Check whether a particular module has been marked as resident, + returning 1 if it has or 0 otherwise. If there is an error while + executing this function, return -1 and set an error message for + retrieval with `lt_dlerror'. + + ---------- Footnotes ---------- + + (1) Some platforms, notably Mac OS X, differentiate between a +runtime library that cannot be opened by `lt_dlopen' and a dynamic +module that can. For maximum portability you should try to ensure that +you only pass `lt_dlopen' objects that have been compiled with libtool's +`-module' flag. + + +File: libtool.info, Node: Modules for libltdl, Next: Thread Safety in libltdl, Prev: Libltdl interface, Up: Using libltdl + +11.2 Creating modules that can be `dlopen'ed +============================================ + +Libtool modules are created like normal libtool libraries with a few +exceptions: + + You have to link the module with libtool's `-module' switch, and you +should link any program that is intended to dlopen the module with +`-dlopen MODULENAME.LA' where possible, so that libtool can dlpreopen +the module on platforms that do not 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 versioning (*note Versioning::) for a specific module +you should link it with the `-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_" (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 that do not use a prefix +so that you can also dlopen non-libtool modules. + + `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. + + /* 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 _foo1_helper(); + } + +The `Makefile.am' contains the necessary rules to build the module +`foo1.la': + + ... + lib_LTLIBRARIES = foo1.la + + foo1_la_SOURCES = foo1.c + foo1_la_LDFLAGS = -module + ... + + +File: libtool.info, Node: Thread Safety in libltdl, Next: User defined module data, Prev: Modules for libltdl, Up: Using libltdl + +11.3 Using libltdl in a multi threaded environment +================================================== + +Libltdl provides a wrapper around whatever dynamic run-time object +loading mechanisms are provided by the host system, many of which are +themselves not thread safe. Consequently libltdl cannot itself be +consistently thread safe. + + If you wish to use libltdl in a multithreaded environment, then you +must mutex lock around libltdl calls, since they may in turn be calling +non-thread-safe system calls on some target hosts. + + Some old releases of libtool provided a mutex locking API that was +unusable with POSIX threads, so callers were forced to lock around all +libltdl API calls anyway. That mutex locking API was next to useless, +and is not present in current releases. + + Some future release of libtool may provide a new POSIX thread +compliant mutex locking API. + + +File: libtool.info, Node: User defined module data, Next: Module loaders for libltdl, Prev: Thread Safety in libltdl, Up: Using libltdl + +11.4 Data associated with loaded modules +======================================== + +Some of the internal information about each loaded module that is +maintained by libltdl is available to the user, in the form of this +structure: + + -- Type: struct lt_dlinfo { char *FILENAME; char *NAME; int REF_COUNT; + int IS_RESIDENT; int IS_SYMGLOBAL; int IS_SYMLOCAL;} + `lt_dlinfo' is used to store information about a module. The + FILENAME attribute is a null-terminated character string of the + real module file name. If the module is a libtool module then + NAME is its module name (e.g. `"libfoo"' for `"dir/libfoo.la"'), + otherwise it is set to `NULL'. The REF_COUNT attribute is a + reference counter that describes how often the same module is + currently loaded. The remaining fields can be compared to any + hints that were passed to `lt_dlopenadvise' to determine whether + the underlying loader was able to follow them. + + The following function will return a pointer to libltdl's internal +copy of this structure for the given HANDLE: + + -- Function: const lt_dlinfo * lt_dlgetinfo (lt_dlhandle HANDLE) + Return a pointer to a struct that contains some information about + the module HANDLE. The contents of the struct must not be + modified. Return `NULL' on failure. + + Furthermore, in order to save you from having to keep a list of the +handles of all the modules you have loaded, these functions allow you to +iterate over libltdl's list of loaded modules: + + -- Type: lt_dlinterface_id + The opaque type used to hold the module interface details for each + registered libltdl client. + + -- Type: int lt_dlhandle_interface (lt_dlhandle HANDLE, + const char *ID_STRING) + Functions of this type are called to check that a handle conforms + to a library's expected module interface when iterating over the + global handle list. You should be careful to write a callback + function of this type that can correctly identify modules that + belong to this client, both to prevent other clients from + accidentally finding your loaded modules with the iterator + functions below, and vice versa. The best way to do this is to + check that module HANDLE conforms to the interface specification + of your loader using `lt_dlsym'. + + The callback may be given *every* module loaded by all the libltdl + module clients in the current address space, including any modules + loaded by other libraries such as libltdl itself, and should + return non-zero if that module does not fulfill the interface + requirements of your loader. + + int + my_interface_cb (lt_dlhandle handle, const char *id_string) + { + char *(*module_id) (void) = NULL; + + /* A valid my_module must provide all of these symbols. */ + if (!((module_id = (char*(*)(void)) lt_dlsym ("module_version")) + && lt_dlsym ("my_module_entrypoint"))) + return 1; + + if (strcmp (id_string, module_id()) != 0) + return 1; + + return 0; + } + + -- Function: lt_dlinterface_id lt_dlinterface_register + (const char *ID_STRING, lt_dlhandle_interface *IFACE) + Use this function to register your interface validator with + libltdl, and in return obtain a unique key to store and retrieve + per-module data. You supply an ID_STRING and IFACE so that the + resulting `lt_dlinterface_id' can be used to filter the module + handles returned by the iteration functions below. If IFACE is + `NULL', all modules will be matched. + + -- Function: void lt_dlinterface_free (lt_dlinterface_id IFACE) + Release the data associated with IFACE. + + -- Function: int lt_dlhandle_map (lt_dlinterface_id IFACE, + int (*FUNC) (lt_dlhandle HANDLE, void * DATA), void * DATA) + For each module that matches IFACE, call the function FUNC. When + writing the FUNC callback function, the argument HANDLE is the + handle of a loaded module, and DATA is the last argument passed to + `lt_dlhandle_map'. As soon as FUNC returns a non-zero value for + one of the handles, `lt_dlhandle_map' will stop calling FUNC and + immediately return that non-zero value. Otherwise 0 is eventually + returned when FUNC has been successfully called for all matching + modules. + + -- Function: lt_dlhandle lt_dlhandle_iterate + (lt_dlinterface_id IFACE, lt_dlhandle PLACE) + Iterate over the module handles loaded by IFACE, returning the + first matching handle in the list if PLACE is `NULL', and the next + one on subsequent calls. If PLACE is the last element in the list + of eligible modules, this function returns `NULL'. + + lt_dlhandle handle = 0; + lt_dlinterface_id iface = my_interface_id; + + while ((handle = lt_dlhandle_iterate (iface, handle))) + { + ... + } + + -- Function: lt_dlhandle lt_dlhandle_fetch (lt_dlinterface_id IFACE, + const char *MODULE_NAME) + Search through the module handles loaded by IFACE for a module + named MODULE_NAME, returning its handle if found or else `NULL' if + no such named module has been loaded by IFACE. + + However, you might still need to maintain your own list of loaded +module handles (in parallel with the list maintained inside libltdl) if +there were any other data that your application wanted to associate +with each open module. Instead, you can use the following API calls to +do that for you. You must first obtain a unique interface id from +libltdl as described above, and subsequently always use it to retrieve +the data you stored earlier. This allows different libraries to each +store their own data against loaded modules, without interfering with +one another. + + -- Function: void * lt_dlcaller_set_data (lt_dlinterface_id KEY, + lt_dlhandle HANDLE, void * DATA) + Set DATA as the set of data uniquely associated with KEY and + HANDLE for later retrieval. This function returns the DATA + previously associated with KEY and HANDLE if any. A result of 0, + may indicate that a diagnostic for the last error (if any) is + available from `lt_dlerror()'. + + For example, to correctly remove some associated data: + + void *stale = lt_dlcaller_set_data (key, handle, 0); + if (stale != NULL) + { + free (stale); + } + else + { + char *error_msg = lt_dlerror (); + + if (error_msg != NULL) + { + my_error_handler (error_msg); + return STATUS_FAILED; + } + } + + -- Function: void * lt_dlcaller_get_data (lt_dlinterface_id KEY, + lt_dlhandle HANDLE) + Return the address of the data associated with KEY and HANDLE, or + else `NULL' if there is none. + + Old versions of libltdl also provided a simpler, but similar, API +based around `lt_dlcaller_id'. Unfortunately, it had no provision for +detecting whether a module belonged to a particular interface as +libltdl didn't support multiple loaders in the same address space at +that time. Those APIs are no longer supported as there would be no way +to stop clients of the old APIs from seeing (and accidentally altering) +modules loaded by other libraries. + + +File: libtool.info, Node: Module loaders for libltdl, Next: Distributing libltdl, Prev: User defined module data, Up: Using libltdl + +11.5 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 `lt_dlopen' will be able +to use it. + + Writing a loader involves writing at least three functions that can +be called by `lt_dlopen', `lt_dlsym' and `lt_dlclose'. Optionally, you +can provide a finalisation function to perform any cleanup operations +when `lt_dlexit' executes, and a symbol prefix string that will be +prepended to any symbols passed to `lt_dlsym'. These functions must +match the function pointer types below, after which they can be +allocated to an instance of `lt_user_dlloader' and registered. + + Registering the loader requires that you choose a name for it, so +that it can be recognised by `lt_dlloader_find' and removed with +`lt_dlloader_remove'. The name you choose must be unique, and not +already in use by libltdl's builtin loaders: + +"dlopen" + The system dynamic library loader, if one exists. + +"dld" + The GNU dld loader, if `libdld' was installed when libltdl was + built. + +"dlpreload" + The loader for `lt_dlopen'ing of preloaded static modules. + + The prefix "dl" is reserved for loaders supplied with future +versions of libltdl, so you should not use that for your own loader +names. + +The following types are defined in `ltdl.h': + + -- Type: lt_module + `lt_module' is a dlloader dependent module. The dynamic module + loader extensions communicate using these low level types. + + -- Type: lt_dlloader + `lt_dlloader' is a handle for module loader types. + + -- Type: lt_user_data + `lt_user_data' is used for specifying loader instance data. + + -- Type: struct lt_user_dlloader {const char *SYM_PREFIX; + lt_module_open *MODULE_OPEN; lt_module_close *MODULE_CLOSE; + lt_find_sym *FIND_SYM; lt_dlloader_exit *DLLOADER_EXIT; } + If you want to define a new way to open dynamic modules, and have + the `lt_dlopen' API use it, you need to instantiate one of these + structures and pass it to `lt_dlloader_add'. You can pass whatever + you like in the DLLOADER_DATA field, and it will be passed back as + the value of the first parameter to each of the functions + specified in the function pointer fields. + + -- Type: lt_module lt_module_open (const char *FILENAME) + The type of the loader function for an `lt_dlloader' module + loader. The value set in the dlloader_data field of the `struct + lt_user_dlloader' structure will be passed into this function in + the LOADER_DATA parameter. Implementation of such a function + should attempt to load the named module, and return an `lt_module' + suitable for passing in to the associated `lt_module_close' and + `lt_sym_find' function pointers. If the function fails it should + return `NULL', and set the error message with `lt_dlseterror'. + + -- Type: int lt_module_close (lt_user_data LOADER_DATA, + lt_module MODULE) + The type of the unloader function for a user defined module loader. + Implementation of such a function should attempt to release any + resources tied up by the MODULE module, and then unload it from + memory. If the function fails for some reason, set the error + message with `lt_dlseterror' and return non-zero. + + -- Type: void * lt_find_sym (lt_module MODULE, const char *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 SYMBOL in the module MODULE, or else set the + error message with `lt_dlseterror' and return `NULL' if lookup + fails. + + -- Type: int lt_dlloader_exit (lt_user_data LOADER_DATA) + 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, including any user specified + data in the `dlloader_data' field of the `lt_user_dlloader'. If + non-`NULL', the function will be called by `lt_dlexit', and + `lt_dlloader_remove'. + + For 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; + dlloader.dlloader_data = (lt_user_data)myloader_function; + + /* Add my loader as the default module loader. */ + if (lt_dlloader_add (lt_dlloader_next (NULL), &dlloader, + "myloader") != 0) + return ERROR; + + return OK; + } + + 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 _is_ handled by libltdl however, and it is important to +ensure the `dlloader_exit' callback releases any resources claimed +during the initialisation phase. + +libltdl provides the following functions for writing your own module +loaders: + + -- Function: int lt_dlloader_add (lt_dlloader *PLACE, + lt_user_dlloader *DLLOADER, const char *LOADER_NAME) + Add a new module loader to the list of all loaders, either as the + last loader (if PLACE is `NULL'), else immediately before the + loader passed as PLACE. LOADER_NAME will be returned by + `lt_dlloader_name' if it is subsequently passed a newly registered + loader. These LOADER_NAMEs must be unique, or + `lt_dlloader_remove' and `lt_dlloader_find' cannot work. Returns + 0 for success. + + /* Make myloader be the last one. */ + if (lt_dlloader_add (NULL, myloader) != 0) + perror (lt_dlerror ()); + + -- Function: int lt_dlloader_remove (const char *LOADER_NAME) + Remove the loader identified by the unique name, 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 `lt_dlerror'. + + /* Remove myloader. */ + if (lt_dlloader_remove ("myloader") != 0) + perror (lt_dlerror ()); + + -- Function: lt_dlloader * lt_dlloader_next (lt_dlloader *PLACE) + Iterate over the module loaders, returning the first loader if + PLACE is `NULL', and the next one on subsequent calls. The handle + is for use with `lt_dlloader_add'. + + /* Make myloader be the first one. */ + if (lt_dlloader_add (lt_dlloader_next (NULL), myloader) != 0) + return ERROR; + + -- Function: lt_dlloader * lt_dlloader_find (const char *LOADER_NAME) + Return the first loader with a matching LOADER_NAME identifier, or + else `NULL', if the identifier is not found. + + The identifiers that may be used by libltdl itself, if the host + architecture supports them are "dlopen"(1), "dld" and "dlpreload". + + /* 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_dlloader_add (lt_dlloader_find ("dlopen"), myloader) != 0) + return ERROR; + + -- Function: const char * lt_dlloader_name (lt_dlloader *PLACE) + Return the identifying name of PLACE, as obtained from + `lt_dlloader_next' or `lt_dlloader_find'. If this function fails, + it will return `NULL' and set an error for retrieval with + `lt_dlerror'. + + -- Function: lt_user_data * lt_dlloader_data (lt_dlloader *PLACE) + Return the address of the `dlloader_data' of PLACE, as obtained + from `lt_dlloader_next' or `lt_dlloader_find'. If this function + fails, it will return `NULL' and set an error for retrieval with + `lt_dlerror'. + +11.5.1 Error handling within user module loaders +------------------------------------------------ + + -- Function: int lt_dladderror (const char *DIAGNOSTIC) + This function allows you to integrate your own error messages into + `lt_dlerror'. Pass in a suitable diagnostic message for return by + `lt_dlerror', and an error identifier for use with `lt_dlseterror' + is returned. + + If the allocation of an identifier fails, this function returns -1. + + int myerror = lt_dladderror ("Doh!"); + if (myerror < 0) + perror (lt_dlerror ()); + + -- Function: int lt_dlseterror (int ERRORCODE) + When writing your own module loaders, you should use this function + to raise errors so that they are propagated through the + `lt_dlerror' interface. All of the standard errors used by + libltdl are declared in `ltdl.h', or you can add more of your own + with `lt_dladderror'. This function returns 0 on success. + + if (lt_dlseterror (LTDL_ERROR_NO_MEMORY) != 0) + perror (lt_dlerror ()); + +---------- Footnotes ---------- + + (1) This is used for the host dependent module loading API - +`shl_load' and `LoadLibrary' for example + + +File: libtool.info, Node: Distributing libltdl, Prev: Module loaders for libltdl, Up: Using libltdl + +11.6 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, or if you are using features of a very new version of +libltdl that you don't expect your users to have yet. In such cases, +you must decide which flavor of libltdl you want to use: a convenience +library or an installable libtool library. + + The most simplistic way to add `libltdl' to your package is to copy +all the `libltdl' source files to a subdirectory within 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 +`ltdl.m4'. You must ensure that they are available in `aclocal.m4' +before you run Autoconf(1). Having made the macros available, you must +add a call to the `LTDL_INIT' macro (after the call to `LT_INIT') to +your package's `configure.ac' to perform the configure time checks +required to build the library correctly. Unfortunately, this method +has problems if you then try to link the package binaries with an +installed libltdl, or a library that depends on libltdl, because of the +duplicate symbol definitions. For example, ultimately linking against +two different versions of libltdl, or against both a local convenience +library and an installed libltdl is bad. Ensuring that only one copy +of the libltdl sources are linked into any program is left as an +exercise for the reader. + + -- Macro: LT_CONFIG_LTDL_DIR (DIRECTORY) + Declare DIRECTORY to be the location of the `libltdl' source + files, for `libtoolize --ltdl' to place them. *Note Invoking + libtoolize::, for more details. Provided that you add an + appropriate `LT_CONFIG_LTDL_DIR' call in your `configure.ac' + before calling `libtoolize', the appropriate `libltdl' files will + be installed automatically. + + -- Macro: LTDL_INIT (OPTIONS) + -- Macro: LT_WITH_LTDL + -- Macro: AC_WITH_LTDL + `AC_WITH_LTDL' and `LT_WITH_LTDL' are deprecated names for older + versions of this macro; `autoupdate' will update your + `configure.ac' file. + + This macro adds the following options to the `configure' script: + + `--with-ltdl-include INSTALLED-LTDL-HEADER-DIR' + The `LTDL_INIT' macro will look in the standard header file + locations to find the installed `libltdl' headers. If + `LTDL_INIT' can't find them by itself, the person who builds + your package can use this option to tell `configure' where + the installed `libltdl' headers are. + + `--with-ltdl-lib INSTALLED-LTDL-LIBRARY-DIR' + Similarly, the person building your package can use this + option to help `configure' find the installed `libltdl.la'. + + `--with-included-ltdl' + If there is no installed `libltdl', or in any case if the + person building your package would rather use the `libltdl' + sources shipped with the package in the subdirectory named by + `LT_CONFIG_LTDL_DIR', they should pass this option to + `configure'. + + If the `--with-included-ltdl' is not passed at configure time, and + an installed `libltdl' is not found(2), then `configure' will exit + immediately with an error that asks the user to either specify the + location of an installed `libltdl' using the `--with-ltdl-include' + and `--with-ltdl-lib' options, or to build with the `libltdl' + sources shipped with the package by passing `--with-included-ltdl'. + + If an installed `libltdl' is found, then `LIBLTDL' is set to the + link flags needed to use it, and `LTDLINCL' to the preprocessor + flags needed to find the installed headers, and `LTDLDEPS' will be + empty. Note, however, that no version checking is performed. You + should manually check for the `libltdl' features you need in + `configure.ac': + + LT_INIT([dlopen]) + LTDL_INIT + + # The lt_dladvise_init symbol was added with libtool-2.2 + if test "x$with_included_ltdl" != "xyes"; then + save_CFLAGS="$CFLAGS" + save_LDFLAGS="$LDFLAGS" + CFLAGS="$CFLAGS $LTDLINCL" + LDFLAGS="$LDFLAGS $LIBLTDL" + AC_CHECK_LIB([ltdl], [lt_dladvise_init], + [], + [AC_MSG_ERROR([installed libltdl is too old])]) + LDFLAGS="$save_LDFLAGS" + CFLAGS="$save_CFLAGS" + fi + + OPTIONS may include no more than one of the following build modes + depending on how you want your project to build `libltdl': + `nonrecursive', `recursive', or `subproject'. In order for + `libtoolize' to detect this option correctly, if you supply one of + these arguments, they must be given literally (i.e., macros or + shell variables that expand to the correct ltdl mode will not + work). + + `nonrecursive' + This is how the Libtool project distribution builds the + `libltdl' we ship and install. If you wish to use Automake + to build `libltdl' without invoking a recursive make to + descend into the `libltdl' subdirectory, then use this + option. You will need to set your configuration up carefully + to make this work properly, and you will need releases of + Autoconf and Automake that support `subdir-objects' and + `LIBOBJDIR' properly. In your `configure.ac', add: + + AM_INIT_AUTOMAKE([subdir-objects]) + AC_CONFIG_HEADERS([config.h]) + LT_CONFIG_LTDL_DIR([libltdl]) + LT_INIT([dlopen]) + LTDL_INIT([nonrecursive]) + + You _have to_ use a config header, but it may have a name + different than `config.h'. + + Also, add the following near the top of your `Makefile.am': + + AM_CPPFLAGS = + AM_LDFLAGS = + + BUILT_SOURCES = + EXTRA_DIST = + CLEANFILES = + MOSTLYCLEANFILES = + + include_HEADERS = + noinst_LTLIBRARIES = + lib_LTLIBRARIES = + EXTRA_LTLIBRARIES = + + include libltdl/Makefile.inc + + Unless you build no other libraries from this `Makefile.am', + you will also need to change `lib_LTLIBRARIES' to assign with + `+=' so that the `libltdl' targets declared in `Makefile.inc' + are not overwritten. + + `recursive' + This build mode still requires that you use Automake, but (in + contrast with `nonrecursive') uses the more usual device of + starting another `make' process in the `libltdl' + subdirectory. To use this mode, you should add to your + `configure.ac': + + AM_INIT_AUTOMAKE + AC_CONFIG_HEADERS([config.h]) + LT_CONFIG_LTDL_DIR([libltdl]) + LT_INIT([dlopen]) + LTDL_INIT([recursive]) + AC_CONFIG_FILES([libltdl/Makefile]) + + Again, you _have to_ use a config header, but it may have a + name different than `config.h' if you like. + + Also, add this to your `Makefile.am': + + SUBDIRS = libltdl + + `subproject' + This mode is the default unless you explicitly add + `recursive' or `nonrecursive' to your `LTDL_INIT' options; + `subproject' is the only mode supported by previous releases + of libltdl. Even if you do not use Autoconf in the parent + project, then, in `subproject' mode, still `libltdl' contains + all the necessary files to configure and build itself - you + just need to arrange for your build system to call + `libltdl/configure' with appropriate options, and then run + `make' in the `libltdl' subdirectory. + + If you _are_ using Autoconf and Automake, then you will need + to add the following to your `configure.ac': + + LT_CONFIG_LTDL_DIR([libltdl]) + LTDL_INIT + + and to `Makefile.am': + + SUBDIRS = libltdl + + Aside from setting the libltdl build mode, there are other keywords + that you can pass to `LTDL_INIT' to modify its behavior when + `--with-included-ltdl' has been given: + + `convenience' + This is the default unless you explicitly add `installable' to + your `LTDL_INIT' options. + + This keyword will cause options to be passed to the + `configure' script in the subdirectory named by + `LT_CONFIG_LTDL_DIR' in order to cause it to be built as a + convenience library. If you're not using automake, you will + need to define `top_build_prefix', `top_builddir', and + `top_srcdir' in your makefile so that `LIBLTDL', `LTDLDEPS', + and `LTDLINCL' expand correctly. + + 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 won't overwrite a pre-installed + version of `libltdl' the system might already have in the + installation directory. 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 the + shared 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 those + libraries, because you may get duplicate symbols. In general + you can safely use the convenience library in programs that + don't depend on other libraries that might use `libltdl' too. + + `installable' + This keyword will pass options to the `configure' script in + the subdirectory named by `LT_CONFIG_LTDL_DIR' in order to + cause it to be built as an installable library. If you're not + using automake, you will need to define `top_build_prefix', + `top_builddir' and `top_srcdir' in your makefile so that + `LIBLTDL', `LTDLDEPS', and `LTDLINCL' are expanded properly. + + Be aware that you could overwrite another `libltdl' already + installed to the same directory if you use this option. + + Whatever method you use, `LTDL_INIT' will define the shell variable +`LIBLTDL' to the link flag that you should use to link with `libltdl', +the shell variable `LTDLDEPS' to the files that can be used as a +dependency in `Makefile' rules, and the shell variable `LTDLINCL' to +the preprocessor flag that you should use to compile programs that +include `ltdl.h'. So, when you want to link a program with libltdl, be +it a convenience, installed or installable library, just use +`$(LTDLINCL)' for preprocessing and compilation, and `$(LIBLTDL)' for +linking. + + * If your package is built using an installed version of `libltdl', + `LIBLTDL' will be set to the compiler flags needed to link against + the installed library, `LTDLDEPS' will be empty, and `LTDLINCL' + will be set to the compiler flags needed to find the `libltdl' + header files. + + * If your package is built using the convenience libltdl, `LIBLTDL' + and `LTDLDEPS' will be the pathname for the convenience version of + libltdl (starting with `${top_builddir}/' or + `${top_build_prefix}') and `LTDLINCL' will be `-I' followed by the + directory that contains `ltdl.h' (starting with `${top_srcdir}/'). + + * If an installable version of the included `libltdl' is being + built, its pathname starting with `${top_builddir}/' or + `${top_build_prefix}', will be stored in `LIBLTDL' and `LTDLDEPS', + and `LTDLINCL' will be set just like in the case of convenience + library. + + You should probably also use the `dlopen' option to `LT_INIT' in +your `configure.ac', otherwise libtool will assume no dlopening +mechanism is supported, and revert to dlpreopening, which is probably +not what you want. Avoid using the `-static', `-static-libtool-libs', +or `-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 an installable libltdl +in your package. In order to use the convenience variant, just replace +the `LTDL_INIT' option `installable' with `convenience'. We assume +that libltdl was embedded using `libtoolize --ltdl'. + + configure.ac: + ... + # Name the subdirectory that contains libltdl sources + LT_CONFIG_LTDL_DIR([libltdl]) + + # Configure libtool with dlopen support if possible + LT_INIT([dlopen]) + + # Enable building of the installable libltdl library + LTDL_INIT([installable]) + ... + + Makefile.am: + ... + SUBDIRS = libltdl + + AM_CPPFLAGS = $(LTDLINCL) + + myprog_LDFLAGS = -export-dynamic + myprog_LDADD = $(LIBLTDL) -dlopen self -dlopen foo1.la + myprog_DEPENDENCIES = $(LTDLDEPS) foo1.la + ... + + -- Macro: LTDL_INSTALLABLE + -- Macro: AC_LIBLTDL_INSTALLABLE + These macros are deprecated, the `installable' option to + `LTDL_INIT' should be used instead. + + -- Macro: LTDL_CONVENIENCE + -- Macro: AC_LIBLTDL_CONVENIENCE + These macros are deprecated, the `convenience' option to + `LTDL_INIT' should be used instead. + + ---------- Footnotes ---------- + + (1) We used to recommend adding the contents of `ltdl.m4' to +`acinclude.m4', but with `aclocal' from a modern Automake (1.8 or +newer) and this release of libltdl that is not only unnecessary but +makes it easy to forget to upgrade `acinclude.m4' if you move to a +different release of libltdl. + + (2) Even if libltdl is installed, `LTDL_INIT' may fail to detect it +if libltdl depends on symbols provided by libraries other than the C +library. + + +File: libtool.info, Node: Trace interface, Next: FAQ, Prev: Using libltdl, Up: Top + +12 Libtool's trace interface +**************************** + +This section describes macros whose sole purpose is to be traced using +Autoconf's `--trace' option (*note The Autoconf Manual: +(autoconf)autoconf Invocation.) to query the Libtool configuration of a +project. These macros are called by Libtool internals and should never +be called by user code; they should only be traced. + + -- Macro: LT_SUPPORTED_TAG (TAG) + This macro is called once for each language enabled in the + package. Its only argument, TAG, is the tag-name corresponding to + the language (*note Tags::). + + You can therefore retrieve the list of all tags enabled in a + project using the following command: + autoconf --trace 'LT_SUPPORTED_TAG:$1' + + +File: libtool.info, Node: FAQ, Next: Troubleshooting, Prev: Trace interface, Up: Top + +13 Frequently Asked Questions about libtool +******************************************* + +This chapter covers some questions that often come up on the mailing +lists. + +* Menu: + +* Stripped link flags:: Dropped flags when creating a library + + +File: libtool.info, Node: Stripped link flags, Up: FAQ + +13.1 Why does libtool strip link flags when creating a library? +=============================================================== + +When creating a shared library, but not when compiling or creating a +program, `libtool' drops some flags from the command line provided by +the user. This is done because flags unknown to `libtool' may +interfere with library creation or require additional support from +`libtool', and because omitting flags is usually the conservative +choice for a successful build. + + If you encounter flags that you think are useful to pass, as a +work-around you can prepend flags with `-Wc,' or `-Xcompiler ' to allow +them to be passed through to the compiler driver (*note Link mode::). +Another possibility is to add flags already to the compiler command at +`configure' run time: + + ./configure CC='gcc -m64' + + If you think `libtool' should let some flag through by default, +here's how you can test such an inclusion: grab the Libtool development +tree, edit the `ltmain.m4sh' file in the `libltdl/config' subdirectory +to pass through the flag (search for `Flags to be passed through'), +re-bootstrap and build with the flags in question added to `LDFLAGS', +`CFLAGS', `CXXFLAGS', etc. on the `configure' command line as +appropriate. Run the testsuite as described in the `README' file and +report results to the Libtool bug reporting address +. + + +File: libtool.info, Node: Troubleshooting, Next: Maintaining, Prev: FAQ, Up: Top + +14 Troubleshooting +****************** + +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. + + +File: libtool.info, Node: Libtool test suite, Next: Reporting bugs, Up: Troubleshooting + +14.1 The libtool test suite +=========================== + +Libtool comes with two integrated sets of tests to check that your build +is sane, 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 `README' file, you may run `make -k 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 old test suite. +* When tests fail:: What to do when a test fails. + + +File: libtool.info, Node: Test descriptions, Next: When tests fail, Up: Libtool test suite + +14.1.1 Description of test suite +-------------------------------- + +Here is a list of the current programs in the old test suite, and what +they test for: + +`cdemo-conf.test' +`cdemo-make.test' +`cdemo-exec.test' +`cdemo-static.test' +`cdemo-static-make.test' +`cdemo-static-exec.test' +`cdemo-shared.test' +`cdemo-shared-make.test' +`cdemo-shared-exec.test' +`cdemo-undef.test' +`cdemo-undef-make.test' +`cdemo-undef-exec.test' + These programs check to see that the `tests/cdemo' subdirectory of + the libtool distribution can be configured and built correctly. + + The `tests/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 matching `cdemo-*make.test' and `cdemo-*exec.test' are + executed three times, under three different libtool configurations: + `cdemo-conf.test' configures `cdemo/libtool' to build both static + and shared libraries (the default for platforms that support + both), `cdemo-static.test' builds only static libraries + (`--disable-shared'), and `cdemo-shared.test' builds only shared + libraries (`--disable-static'). + + The test `cdemo-undef.test' tests the generation of shared + libraries with undefined symbols on systems that allow this. + +`demo-conf.test' +`demo-make.test' +`demo-exec.test' +`demo-inst.test' +`demo-unst.test' +`demo-static.test' +`demo-static-make.test' +`demo-static-exec.test' +`demo-static-inst.test' +`demo-static-unst.test' +`demo-shared.test' +`demo-shared-make.test' +`demo-shared-exec.test' +`demo-shared-inst.test' +`demo-shared-unst.test' +`demo-nofast.test' +`demo-nofast-make.test' +`demo-nofast-exec.test' +`demo-nofast-inst.test' +`demo-nofast-unst.test' +`demo-pic.test' +`demo-pic-make.test' +`demo-pic-exec.test' +`demo-nopic.test' +`demo-nopic-make.test' +`demo-nopic-exec.test' + These programs check to see that the `tests/demo' subdirectory of + the libtool distribution can be configured, built, installed, and + uninstalled correctly. + + The `tests/demo' subdirectory contains a demonstration of a trivial + package that uses libtool. The tests matching `demo-*make.test', + `demo-*exec.test', `demo-*inst.test' and `demo-*unst.test' are + executed four times, under four different libtool configurations: + `demo-conf.test' configures `demo/libtool' to build both static + and shared libraries, `demo-static.test' builds only static + libraries (`--disable-shared'), and `demo-shared.test' builds only + shared libraries (`--disable-static'). `demo-nofast.test' + configures `demo/libtool' to disable the fast-install mode + (`--enable-fast-install=no'). `demo-pic.test' configures + `demo/libtool' to prefer building PIC code (`--with-pic'), + `demo-nopic.test' to prefer non-PIC code (`--without-pic'). + +`demo-deplibs.test' + Many systems cannot link static libraries into shared libraries. + libtool uses a `deplibs_check_method' to prevent such cases. This + tests checks whether libtool's `deplibs_check_method' works + properly. + +`demo-hardcode.test' + On all systems with shared libraries, the location of the library + can be encoded in executables that are linked against it *note + 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. + +`demo-relink.test' +`depdemo-relink.test' + These tests check whether variable `shlibpath_overrides_runpath' is + properly set. If the test fails, it will indicate what the + variable should have been set to. + +`demo-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. + +`depdemo-conf.test' +`depdemo-make.test' +`depdemo-exec.test' +`depdemo-inst.test' +`depdemo-unst.test' +`depdemo-static.test' +`depdemo-static-make.test' +`depdemo-static-exec.test' +`depdemo-static-inst.test' +`depdemo-static-unst.test' +`depdemo-shared.test' +`depdemo-shared-make.test' +`depdemo-shared-exec.test' +`depdemo-shared-inst.test' +`depdemo-shared-unst.test' +`depdemo-nofast.test' +`depdemo-nofast-make.test' +`depdemo-nofast-exec.test' +`depdemo-nofast-inst.test' +`depdemo-nofast-unst.test' + These programs check to see that the `tests/depdemo' subdirectory + of the libtool distribution can be configured, built, installed, + and uninstalled correctly. + + The `tests/depdemo' subdirectory contains a demonstration of + inter-library dependencies with libtool. The test programs link + some interdependent libraries. + + The tests matching `depdemo-*make.test', `depdemo-*exec.test', + `depdemo-*inst.test' and `depdemo-*unst.test' are executed four + times, under four different libtool configurations: + `depdemo-conf.test' configures `depdemo/libtool' to build both + static and shared libraries, `depdemo-static.test' builds only + static libraries (`--disable-shared'), and `depdemo-shared.test' + builds only shared libraries (`--disable-static'). + `depdemo-nofast.test' configures `depdemo/libtool' to disable the + fast-install mode (`--enable-fast-install=no'). + +`mdemo-conf.test' +`mdemo-make.test' +`mdemo-exec.test' +`mdemo-inst.test' +`mdemo-unst.test' +`mdemo-static.test' +`mdemo-static-make.test' +`mdemo-static-exec.test' +`mdemo-static-inst.test' +`mdemo-static-unst.test' +`mdemo-shared.test' +`mdemo-shared-make.test' +`mdemo-shared-exec.test' +`mdemo-shared-inst.test' +`mdemo-shared-unst.test' + These programs check to see that the `tests/mdemo' subdirectory of + the libtool distribution can be configured, built, installed, and + uninstalled correctly. + + The `tests/mdemo' subdirectory contains a demonstration of a + package that uses libtool and the system independent dlopen wrapper + `libltdl' to load modules. The library `libltdl' provides a + dlopen wrapper for various platforms (POSIX) including support for + dlpreopened modules (*note Dlpreopening::). + + The tests matching `mdemo-*make.test', `mdemo-*exec.test', + `mdemo-*inst.test' and `mdemo-*unst.test' are executed three + times, under three different libtool configurations: + `mdemo-conf.test' configures `mdemo/libtool' to build both static + and shared libraries, `mdemo-static.test' builds only static + libraries (`--disable-shared'), and `mdemo-shared.test' builds + only shared libraries (`--disable-static'). + +`mdemo-dryrun.test' + This test checks whether libtool's `--dry-run' mode works properly. + +`mdemo2-conf.test' +`mdemo2-exec.test' +`mdemo2-make.test' + These programs check to see that the `tests/mdemo2' subdirectory of + the libtool distribution can be configured, built, and executed + correctly. + + The `tests/mdemo2' directory contains a demonstration of a package + that attempts to link with a library (from the `tests/mdemo' + directory) that itself does dlopening of libtool modules. + +`link.test' + This test guarantees that linking directly against a non-libtool + static library works properly. + +`link-2.test' + This test makes sure that files ending in `.lo' are never linked + directly into a program file. + +`nomode.test' + Check whether we can actually get help for libtool. + +`objectlist.test' + Check that a nonexistent objectlist file is properly detected. + +`pdemo-conf.test' +`pdemo-make.test' +`pdemo-exec.test' +`pdemo-inst.test' + These programs check to see that the `tests/pdemo' subdirectory of + the libtool distribution can be configured, built, and executed + correctly. + + The `pdemo-conf.test' lowers the `max_cmd_len' variable in the + generated libtool script to test the measures to evade command line + length limitations. + +`quote.test' + This program checks libtool's metacharacter quoting. + +`sh.test' + Checks for some nonportable or dubious or undesired shell + constructs in shell scripts. + +`suffix.test' + When other programming languages are used with libtool (*note + Other languages::), the source files may end in suffixes other + than `.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. + +`tagdemo-conf.test' +`tagdemo-make.test' +`tagdemo-exec.test' +`tagdemo-static.test' +`tagdemo-static-make.test' +`tagdemo-static-exec.test' +`tagdemo-shared.test' +`tagdemo-shared-make.test' +`tagdemo-shared-exec.test' +`tagdemo-undef.test' +`tagdemo-undef-make.test' +`tagdemo-undef-exec.test' + These programs check to see that the `tests/tagdemo' subdirectory + of the libtool distribution can be configured, built, and executed + correctly. + + The `tests/tagdemo' directory contains a demonstration of a package + that uses libtool's multi-language support through configuration + tags. It generates a library from C++ sources, which is then + linked to a C++ program. + +`f77demo-conf.test' +`f77demo-make.test' +`f77demo-exec.test' +`f77demo-static.test' +`f77demo-static-make.test' +`f77demo-static-exec.test' +`f77demo-shared.test' +`f77demo-shared-make.test' +`f77demo-shared-exec.test' + These programs check to see that the `tests/f77demo' subdirectory + of the libtool distribution can be configured, built, and executed + correctly. + + The `tests/f77demo' tests test Fortran 77 support in libtool by + creating libraries from Fortran 77 sources, and mixed Fortran and C + sources, and a Fortran 77 program to use the former library, and a + C program to use the latter library. + +`fcdemo-conf.test' +`fcdemo-make.test' +`fcdemo-exec.test' +`fcdemo-static.test' +`fcdemo-static-make.test' +`fcdemo-static-exec.test' +`fcdemo-shared.test' +`fcdemo-shared-make.test' +`fcdemo-shared-exec.test' + These programs check to see that the `tests/fcdemo' subdirectory + of the libtool distribution can be configured, built, and executed + correctly. + + The `tests/fcdemo' is similar to the `tests/f77demo' directory, + except that Fortran 90 is used in combination with the `FC' + interface provided by Autoconf and Automake. + + + The new, Autotest-based test suite uses keywords to classify certain +test groups: + +`CXX' +`F77' +`FC' +`GCJ' + The test group exercises one of these `libtool' language tags. + +`autoconf' +`automake' + These keywords denote that the respective external program is + needed by the test group. The tests are typically skipped if the + program is not installed. The `automake' keyword may also denote + use of the `aclocal' program. + +`interactive' + This test group may require user interaction on some systems. + Typically, this means closing a popup window about a DLL load + error on Windows. + +`libltdl' + Denote that the `libltdl' library is exercised by the test group. + +`libtool' +`libtoolize' + Denote that the `libtool' or `libtoolize' scripts are exercised by + the test group, respectively. + +`recursive' + Denote that this test group may recursively re-invoke the test + suite itself, with changed settings and maybe a changed `libtool' + script. You may use the `INNER_TESTSUITEFLAGS' variable to pass + additional settings to this recursive invocation. Typically, + recursive invocations delimit the set of tests with another + keyword, for example by passing `-k libtool' right before the + expansion of the `INNER_TESTSUITEFLAGS' variable (without an + intervening space, so you get the chance for further delimitation). + + Test groups with the keyword `recursive' should not be denoted with + keywords, in order to avoid infinite recursion. As a consequence, + recursive test groups themselves should never require user + interaction, while the test groups they invoke may do so. + + There is a convenience target `check-noninteractive' that runs all +tests from both test suites that do not cause user interaction on +Windows. Conversely, the target `check-interactive' runs the +complement of tests and might require closing popup windows about DLL +load errors on Windows. + + +File: libtool.info, Node: When tests fail, Prev: Test descriptions, Up: Libtool test suite + +14.1.2 When tests fail +---------------------- + +When the tests in the old test suite are run via `make check', output +is caught in per-test `tests/TEST-NAME.log' files and summarized in the +`test-suite.log' file. The exit status of each program tells the +`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 that may be useful in determining what the problem is. + + The new, Autotest-based test suite produces as output a file +`tests/testsuite.log' which contains information about failed tests. + + You can pass options to the test suite through the `make' variable +`TESTSUITEFLAGS' (*note The Autoconf Manual: (autoconf)testsuite +Invocation.). + + +File: libtool.info, Node: Reporting bugs, Prev: Libtool test suite, Up: Troubleshooting + +14.2 Reporting bugs +=================== + +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 +(*note 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 (*note +Reporting Bugs: (emacs)Bugs.). 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 the Libtool bug reporting address + with any appropriate _facts_, such as test suite +output (*note 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 +`libtool --version'). + + +File: libtool.info, Node: Maintaining, Next: GNU Free Documentation License, Prev: Troubleshooting, Up: Top + +15 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. + + +File: libtool.info, Node: New ports, Next: Tested platforms, Up: Maintaining + +15.1 Porting libtool to new systems +=================================== + +Before you embark on porting libtool to an unsupported system, it is +worthwhile to send e-mail to the Libtool mailing list +, 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 + + +File: libtool.info, Node: Information sources, Next: Porting inter-library dependencies, Up: New ports + +15.1.1 Information sources +-------------------------- + +Once it is clear that a new port is necessary, you'll generally need the +following information: + +canonical system name + You need the output of `config.guess' for this system, so that you + can make changes to the libtool configuration process without + affecting other systems. + +man pages for `ld' and `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. + +man pages for `ld.so', `rtld', or equivalent + These are a valuable resource for understanding how shared + libraries are loaded on the system. + +man page for `ldconfig', or equivalent + This page usually describes how to install shared libraries. + +output from `ls -l /lib /usr/lib' + This shows the naming convention for shared libraries on the + system, including which names should be symbolic links. + +any additional documentation + Some systems have special documentation on how to build and install + shared libraries. + + 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 +`libtool.m4' macros in order to make platform-specific changes to the +configuration process. You should search that file for the `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 (*note 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 `ltmain.in' script accordingly. Be sure to write to the mailing +list before you make changes to `ltmain.in', since they may have advice +on the most effective way of accomplishing what you want. + + +File: libtool.info, Node: Porting inter-library dependencies, Prev: Information sources, Up: New ports + +15.1.2 Porting inter-library dependencies support +------------------------------------------------- + +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 . Here's a shortened version of the +message that contained his patch: + + The basic architecture is this: in `libtool.m4', the person who +writes libtool makes sure `$deplibs' is included in `$archive_cmds' +somewhere and also sets the variable `$deplibs_check_method', and maybe +`$file_magic_cmd' when `deplibs_check_method' is file_magic. + + `deplibs_check_method' can be one of five things: +`file_magic [REGEX]' + looks in the library link path for libraries that have the right + libname. Then it runs `$file_magic_cmd' on the library and checks + for a match against the extended regular expression REGEX. When + `file_magic_test_file' is set by `libtool.m4', it is used as an + argument to `$file_magic_cmd' in order to verify whether the + regular expression matches its output, and warn the user otherwise. + +`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 + `ldd'. It is currently unused, and will probably be dropped in the + future. + +`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. + +`none' + It causes deplibs to be reassigned `deplibs=""'. That way + `archive_cmds' can contain deplibs on all platforms, but not have + deplibs used unless needed. + +`unknown' + is the default for all systems unless overridden in `libtool.m4'. + It is the same as `none', but it documents that we really don't + know what the correct value should be, and we welcome patches that + improve it. + + Then in `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 the +method that 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. + + +File: libtool.info, Node: Tested platforms, Next: Platform quirks, Prev: New ports, Up: Maintaining + +15.2 Tested platforms +===================== + +This table describes when libtool was last known to be tested on +platforms where it claims to support shared libraries: + + ------------------------------------------------------- + canonical host name compiler libtool results + (tools versions) release + ------------------------------------------------------- + alpha-dec-osf5.1 cc 1.3e ok (1.910) + alpha-dec-osf4.0f gcc 1.3e ok (1.910) + alpha-dec-osf4.0f cc 1.3e ok (1.910) + alpha-dec-osf3.2 gcc 0.8 ok + alpha-dec-osf3.2 cc 0.8 ok + alpha-dec-osf2.1 gcc 1.2f NS + alpha*-unknown-linux-gnu gcc 1.3b ok + (egcs-1.1.2, GNU ld 2.9.1.0.23) + hppa2.0w-hp-hpux11.00 cc 1.2f ok + hppa2.0-hp-hpux10.20 cc 1.3.2 ok + hppa1.1-hp-hpux10.20 gcc 1.2f ok + hppa1.1-hp-hpux10.20 cc 1.3c ok (1.821) + hppa1.1-hp-hpux10.10 gcc 1.2f ok + hppa1.1-hp-hpux10.10 cc 1.2f ok + hppa1.1-hp-hpux9.07 gcc 1.2f ok + hppa1.1-hp-hpux9.07 cc 1.2f ok + hppa1.1-hp-hpux9.05 gcc 1.2f ok + hppa1.1-hp-hpux9.05 cc 1.2f ok + hppa1.1-hp-hpux9.01 gcc 1.2f ok + hppa1.1-hp-hpux9.01 cc 1.2f ok + i*86-*-beos gcc 1.2f ok + i*86-*-bsdi4.0.1 gcc 1.3c ok + (gcc-2.7.2.1) + i*86-*-bsdi4.0 gcc 1.2f ok + i*86-*-bsdi3.1 gcc 1.2e NS + i*86-*-bsdi3.0 gcc 1.2e NS + i*86-*-bsdi2.1 gcc 1.2e NS + i*86-pc-cygwin gcc 1.3b NS + (egcs-1.1 stock b20.1 compiler) + i*86-*-dguxR4.20MU01 gcc 1.2 ok + i*86-*-freebsd4.3 gcc 1.3e ok (1.912) + i*86-*-freebsdelf4.0 gcc 1.3c ok + (egcs-1.1.2) + i*86-*-freebsdelf3.2 gcc 1.3c ok + (gcc-2.7.2.1) + i*86-*-freebsdelf3.1 gcc 1.3c ok + (gcc-2.7.2.1) + i*86-*-freebsdelf3.0 gcc 1.3c ok + i*86-*-freebsd3.0 gcc 1.2e ok + i*86-*-freebsd2.2.8 gcc 1.3c ok + (gcc-2.7.2.1) + i*86-*-freebsd2.2.6 gcc 1.3b ok + (egcs-1.1 & gcc-2.7.2.1, native ld) + i*86-*-freebsd2.1.5 gcc 0.5 ok + i*86-*-netbsd1.5 gcc 1.3e ok (1.901) + (egcs-1.1.2) + i*86-*-netbsd1.4 gcc 1.3c ok + (egcs-1.1.1) + i*86-*-netbsd1.4.3A gcc 1.3e ok (1.901) + i*86-*-netbsd1.3.3 gcc 1.3c ok + (gcc-2.7.2.2+myc2) + i*86-*-netbsd1.3.2 gcc 1.2e ok + i*86-*-netbsd1.3I gcc 1.2e ok + (egcs 1.1?) + i*86-*-netbsd1.2 gcc 0.9g ok + i*86-*-linux-gnu gcc 1.3e ok (1.901) + (Red Hat 7.0, gcc "2.96") + i*86-*-linux-gnu gcc 1.3e ok (1.911) + (SuSE 7.0, gcc 2.95.2) + i*86-*-linux-gnulibc1 gcc 1.2f ok + i*86-*-openbsd2.5 gcc 1.3c ok + (gcc-2.8.1) + i*86-*-openbsd2.4 gcc 1.3c ok + (gcc-2.8.1) + i*86-*-solaris2.7 gcc 1.3b ok + (egcs-1.1.2, native ld) + i*86-*-solaris2.6 gcc 1.2f ok + i*86-*-solaris2.5.1 gcc 1.2f ok + i*86-ncr-sysv4.3.03 gcc 1.2f ok + i*86-ncr-sysv4.3.03 cc 1.2e ok + (cc -Hnocopyr) + i*86-pc-sco3.2v5.0.5 cc 1.3c ok + i*86-pc-sco3.2v5.0.5 gcc 1.3c ok + (gcc 95q4c) + i*86-pc-sco3.2v5.0.5 gcc 1.3c ok + (egcs-1.1.2) + i*86-sco-sysv5uw7.1.1 gcc 1.3e ok (1.901) + (gcc-2.95.2, SCO linker) + i*86-UnixWare7.1.0-sysv5 cc 1.3c ok + i*86-UnixWare7.1.0-sysv5 gcc 1.3c ok + (egcs-1.1.1) + m68k-next-nextstep3 gcc 1.2f NS + m68k-sun-sunos4.1.1 gcc 1.2f NS + (gcc-2.5.7) + m88k-dg-dguxR4.12TMU01 gcc 1.2 ok + m88k-motorola-sysv4 gcc 1.3 ok + (egcs-1.1.2) + mips-sgi-irix6.5 gcc 1.2f ok + (gcc-2.8.1) + mips-sgi-irix6.4 gcc 1.2f ok + mips-sgi-irix6.3 gcc 1.3b ok + (egcs-1.1.2, native ld) + mips-sgi-irix6.3 cc 1.3b ok + (cc 7.0) + mips-sgi-irix6.2 gcc 1.2f ok + mips-sgi-irix6.2 cc 0.9 ok + mips-sgi-irix5.3 gcc 1.2f ok + (egcs-1.1.1) + mips-sgi-irix5.3 gcc 1.2f NS + (gcc-2.6.3) + mips-sgi-irix5.3 cc 0.8 ok + mips-sgi-irix5.2 gcc 1.3b ok + (egcs-1.1.2, native ld) + mips-sgi-irix5.2 cc 1.3b ok + (cc 3.18) + mips-sni-sysv4 cc 1.3.5 ok + (Siemens C-compiler) + mips-sni-sysv4 gcc 1.3.5 ok + (gcc-2.7.2.3, GNU assembler 2.8.1, native ld) + mipsel-unknown-openbsd2.1 gcc 1.0 ok + powerpc-apple-darwin6.4 gcc 1.5 ok + (apple dev tools released 12/2002) + powerpc-ibm-aix4.3.1.0 gcc 1.2f ok + (egcs-1.1.1) + powerpc-ibm-aix4.2.1.0 gcc 1.2f ok + (egcs-1.1.1) + powerpc-ibm-aix4.1.5.0 gcc 1.2f ok + (egcs-1.1.1) + powerpc-ibm-aix4.1.5.0 gcc 1.2f NS + (gcc-2.8.1) + powerpc-ibm-aix4.1.4.0 gcc 1.0 ok + powerpc-ibm-aix4.1.4.0 xlc 1.0i ok + rs6000-ibm-aix4.1.5.0 gcc 1.2f ok + (gcc-2.7.2) + rs6000-ibm-aix4.1.4.0 gcc 1.2f ok + (gcc-2.7.2) + rs6000-ibm-aix3.2.5 gcc 1.0i ok + rs6000-ibm-aix3.2.5 xlc 1.0i ok + sparc-sun-solaris2.8 gcc 1.3e ok (1.913) + (gcc-2.95.3 & native ld) + sparc-sun-solaris2.7 gcc 1.3e ok (1.913) + (gcc-2.95.3 & native ld) + sparc-sun-solaris2.6 gcc 1.3e ok (1.913) + (gcc-2.95.3 & native ld) + sparc-sun-solaris2.5.1 gcc 1.3e ok (1.911) + sparc-sun-solaris2.5 gcc 1.3b ok + (egcs-1.1.2, GNU ld 2.9.1 & native ld) + sparc-sun-solaris2.5 cc 1.3b ok + (SC 3.0.1) + sparc-sun-solaris2.4 gcc 1.0a ok + sparc-sun-solaris2.4 cc 1.0a ok + sparc-sun-solaris2.3 gcc 1.2f ok + sparc-sun-sunos4.1.4 gcc 1.2f ok + sparc-sun-sunos4.1.4 cc 1.0f ok + sparc-sun-sunos4.1.3_U1 gcc 1.2f ok + sparc-sun-sunos4.1.3C gcc 1.2f ok + sparc-sun-sunos4.1.3 gcc 1.3b ok + (egcs-1.1.2, GNU ld 2.9.1 & native ld) + sparc-sun-sunos4.1.3 cc 1.3b ok + sparc-unknown-bsdi4.0 gcc 1.2c ok + sparc-unknown-linux-gnulibc1 gcc 1.2f ok + sparc-unknown-linux-gnu gcc 1.3b ok + (egcs-1.1.2, GNU ld 2.9.1.0.23) + sparc64-unknown-linux-gnu gcc 1.2f ok + + Notes: + - "ok" means "all tests passed". + - "NS" means "Not Shared", but OK for static libraries + + Note: The vendor-distributed HP-UX `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 +`sed' (such as GNU `sed') on these systems. + + Note: The vendor-distributed NCR MP-RAS `cc' programs emits +copyright on standard error that confuse tests on size of +`conftest.err'. The workaround is to specify `CC' when run `configure' +with `CC='cc -Hnocopyr''. + + +File: libtool.info, Node: Platform quirks, Next: libtool script contents, Prev: Tested platforms, Up: Maintaining + +15.3 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. +* Multiple dependencies:: Removing duplicate dependent libraries. +* Archivers:: Programs that create static archives. +* Cross compiling:: Issues that arise when cross compiling. +* File name conversion:: Converting file names between platforms. +* Windows DLLs:: Windows header defines. + + +File: libtool.info, Node: References, Next: Compilers, Up: Platform quirks + +15.3.1 References +----------------- + +The following is a list of valuable documentation references: + + * SGI's IRIX Manual Pages can be found at + `http://techpubs.sgi.com/cgi-bin/infosrch.cgi?cmd=browse&db=man'. + + * Sun's free service area + (`http://www.sun.com/service/online/free.html') and documentation + server (`http://docs.sun.com/'). + + * Compaq's Tru64 UNIX online documentation is at + (`http://tru64unix.compaq.com/faqs/publications/pub_page/doc_list.html') + with C++ documentation at + (`http://tru64unix.compaq.com/cplus/docs/index.htm'). + + * Hewlett-Packard has online documentation at + (`http://docs.hp.com/index.html'). + + * IBM has online documentation at + (`http://www.rs6000.ibm.com/resource/aix_resource/Pubs/'). + + +File: libtool.info, Node: Compilers, Next: Reloadable objects, Prev: References, Up: Platform quirks + +15.3.2 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: + +`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 `-fpic' or `-fPIC' flags can be used to generate + position-independent code. `-fPIC' is guaranteed to generate + working code, but the code is slower on m68k, m88k, and Sparc + chips. However, using `-fpic' on those chips imposes arbitrary + size limits on the shared libraries. + + The rest of this subsection lists compilers by the operating system +that they are bundled with: + +`aix3*' +`aix4*' + Most AIX compilers have no PIC flags, since AIX (with the + exception of AIX for IA-64) runs on PowerPC and RS/6000 chips. (1) + +`hpux10*' + Use `+Z' to generate PIC. + +`osf3*' + Digital/UNIX 3.x does not have PIC flags, at least not on the + PowerPC platform. + +`solaris2*' + Use `-KPIC' to generate PIC. + +`sunos4*' + Use `-PIC' to generate PIC. + + ---------- Footnotes ---------- + + (1) All code compiled for the PowerPC and RS/6000 chips +(`powerpc-*-*', `powerpcle-*-*', and `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. + + +File: libtool.info, Node: Reloadable objects, Next: Multiple dependencies, Prev: Compilers, Up: Platform quirks + +15.3.3 Reloadable objects +------------------------- + +On all known systems, a reloadable object can be created by running `ld +-r -o OUTPUT.o INPUT1.o INPUT2.o'. This reloadable object may be +treated as exactly equivalent to other objects. + + +File: libtool.info, Node: Multiple dependencies, Next: Archivers, Prev: Reloadable objects, Up: Platform quirks + +15.3.4 Multiple dependencies +---------------------------- + +On most modern platforms the order in which dependent libraries are +listed has no effect on object generation. In theory, there are +platforms that require libraries that provide missing symbols to other +libraries to be listed after those libraries whose symbols they provide. + + Particularly, if a pair of static archives each resolve some of the +other's symbols, it might be necessary to list one of those archives +both before and after the other one. Libtool does not currently cope +with this situation well, since duplicate libraries are removed from +the link line by default. Libtool provides the command line option +`--preserve-dup-deps' to preserve all duplicate dependencies in cases +where it is necessary. + + +File: libtool.info, Node: Archivers, Next: Cross compiling, Prev: Multiple dependencies, Up: Platform quirks + +15.3.5 Archivers +---------------- + +On all known systems, building a static library can be accomplished by +running `ar cru libNAME.a OBJ1.o OBJ2.o ...', where the `.a' file is +the output library, and each `.o' file is an object file. + + On all known systems, if there is a program named `ranlib', then it +must be used to "bless" the created library before linking against it, +with the `ranlib libNAME.a' command. Some systems, like Irix, use the +`ar ts' command, instead. + + +File: libtool.info, Node: Cross compiling, Next: File name conversion, Prev: Archivers, Up: Platform quirks + +15.3.6 Cross compiling +---------------------- + +Most build systems support the ability to compile libraries and +applications on one platform for use on a different platform, provided +a compiler capable of generating the appropriate output is available. +In such cross compiling scenarios, the platform on which the libraries +or applications are compiled is called the "build platform", while the +platform on which the libraries or applications are intended to be used +or executed is called the "host platform". *note The GNU Build System: +(automake)GNU Build System, of which libtool is a part, supports cross +compiling via arguments passed to the configure script: `--build=...' +and `--host=...'. However, when the build platform and host platform +are very different, libtool is required to make certain accommodations +to support these scenarios. + + In most cases, because the build platform and host platform differ, +the cross-compiled libraries and executables can't be executed or +tested on the build platform where they were compiled. The testsuites +of most build systems will often skip any tests that involve executing +such foreign executables when cross-compiling. However, if the build +platform and host platform are sufficiently similar, it is often +possible to run cross-compiled applications. Libtool's own testsuite +often attempts to execute cross-compiled tests, but will mark any +failures as _skipped_ since the failure might simply be due to the +differences between the two platforms. + + In addition to cases where the host platform and build platform are +extremely similar (e.g. `i586-pc-linux-gnu' and `i686-pc-linux-gnu'), +there is another case in which cross-compiled host applications may be +executed on the build platform. This is possible when the build +platform supports an emulation or API-enhanced environment for the host +platform. One example of this situation would be if the build platform +were MinGW, and the host platform were Cygwin (or vice versa). Both of +these platforms can actually operate within a single Windows instance, +so Cygwin applications can be launched from a MinGW context, and vice +versa--provided certain care is taken. Another example would be if the +build platform were GNU/Linux on an x86 32bit processor, and the host +platform were MinGW. In this situation, the Wine +(http://www.winehq.org/) environment can be used to launch Windows +applications from the GNU/Linux operating system; again, provided +certain care is taken. + + One particular issue occurs when a Windows platform such as MinGW, +Cygwin, or MSYS is the host or build platform, while the other platform +is a Unix-style system. In these cases, there are often conflicts +between the format of the file names and paths expected within host +platform libraries and executables, and those employed on the build +platform. + + This situation is best described using a concrete example: suppose +the build platform is GNU/Linux with canonical triplet +`i686-pc-linux-gnu'. Suppose further that the host platform is MinGW +with canonical triplet `i586-pc-mingw32'. On the GNU/Linux platform +there is a cross compiler following the usual naming conventions of +such compilers, where the compiler name is prefixed by the host +canonical triplet (or suitable alias). (For more information +concerning canonical triplets and platform aliases, see *note +Specifying Target Triplets: (autoconf)Specifying Target Triplets. and +*note Canonicalizing: (autoconf)Canonicalizing.) In this case, the C +compiler is named `i586-pc-mingw32-gcc'. + + As described in *note Wrapper executables::, for the MinGW host +platform libtool uses a wrapper executable to set various environment +variables before launching the actual program executable. Like the +program executable, the wrapper executable is cross-compiled for the +host platform (that is, for MinGW). As described above, ordinarily a +host platform executable cannot be executed on the build platform, but +in this case the Wine environment could be used to launch the MinGW +application from GNU/Linux. However, the wrapper executable, as a host +platform (MinGW) application, must set the `PATH' variable so that the +true application's dependent libraries can be located--but the contents +of the `PATH' variable must be structured for MinGW. Libtool must use +the Wine file name mapping facilities to determine the correct value so +that the wrapper executable can set the `PATH' variable to point to the +correct location. + + For example, suppose we are compiling an application in `/var/tmp' on +GNU/Linux, using separate source code and build directories: + + `/var/tmp/foo-1.2.3/app/' (application source code) + `/var/tmp/foo-1.2.3/lib/' (library source code) + `/var/tmp/BUILD/app/' (application build objects here) + `/var/tmp/BUILD/lib/' (library build objects here) + + Since the library will be built in `/var/tmp/BUILD/lib', the wrapper +executable (which will be in `/var/tmp/BUILD/app') must add that +directory to `PATH' (actually, it must add the directory named OBJDIR +under `/var/tmp/BUILD/lib', but we'll ignore that detail for now). +However, Windows does not have a concept of Unix-style file or +directory names such as `/var/tmp/BUILD/lib'. Therefore, Wine provides +a mapping from Windows file names such as `C:\Program Files' to specific +Unix-style file names. Wine also provides a utility that can be used +to map Unix-style file names to Windows file names. + + In this case, the wrapper executable should actually add the value + + Z:\var\tmp\BUILD\lib + +to the `PATH'. libtool contains support for path conversions of this +type, for a certain limited set of build and host platform +combinations. In this case, libtool will invoke Wine's `winepath' +utility to ensure that the correct `PATH' value is used. For more +information, see *note File name conversion::. + + +File: libtool.info, Node: File name conversion, Next: Windows DLLs, Prev: Cross compiling, Up: Platform quirks + +15.3.7 File name conversion +--------------------------- + +In certain situations, libtool must convert file names and paths between +formats appropriate to different platforms. Usually this occurs when +cross-compiling, and affects only the ability to launch host platform +executables on the build platform using an emulation or API-enhancement +environment such as Wine. Failure to convert paths (*note File Name +Conversion Failure::) will cause a warning to be issued, but rarely +causes the build to fail--and should have no affect on the compiled +products, once installed properly on the host platform. For more +information, *note Cross compiling::. + + However, file name conversion may also occur in another scenario: +when using a Unix emulation system on Windows (such as Cygwin or MSYS), +combined with a native Windows compiler such as MinGW or MSVC. Only a +limited set of such scenarios are currently supported; in other cases +file name conversion is skipped. The lack of file name conversion +usually means that uninstalled executables can't be launched, but only +rarely causes the build to fail (*note File Name Conversion Failure::). + + libtool supports file name conversion in the following scenarios: + +build platform host platform Notes +--------------------------------------------------------------------------- +MinGW (MSYS) MinGW (Windows) *note Native MinGW File Name + Conversion:: +Cygwin MinGW (Windows) *note Cygwin/Windows File Name + Conversion:: +Unix + Wine MinGW (Windows) Requires Wine. *note Unix/Windows + File Name Conversion:: +MinGW (MSYS) Cygwin Requires `LT_CYGPATH'. *note + LT_CYGPATH::. Provided for testing + purposes only. +Unix + Wine Cygwin Requires both Wine and + `LT_CYGPATH', but does not yet work + with Cygwin 1.7.7 and Wine-1.2. + See *note Unix/Windows File Name + Conversion:: and *note LT_CYGPATH::. + +* Menu: + +* File Name Conversion Failure:: What happens when file name conversion fails +* Native MinGW File Name Conversion:: MSYS file name conversion idiosyncrasies +* Cygwin/Windows File Name Conversion:: Using `cygpath' to convert Cygwin file names +* Unix/Windows File Name Conversion:: Using Wine to convert Unix paths +* LT_CYGPATH:: Invoking `cygpath' from other environments +* Cygwin to MinGW Cross:: Other notes concerning MinGW cross + + +File: libtool.info, Node: File Name Conversion Failure, Next: Native MinGW File Name Conversion, Up: File name conversion + +15.3.7.1 File Name Conversion Failure +..................................... + +In most cases, file name conversion is not needed or attempted. +However, when libtool detects that a specific combination of build and +host platform does require file name conversion, it is possible that +the conversion may fail. In these cases, you may see a warning such as +the following: + + Could not determine the host file name corresponding to + `... a file name ...' + Continuing, but uninstalled executables may not work. + +or + + Could not determine the host path corresponding to + `... a path ...' + Continuing, but uninstalled executables may not work. + +This should not cause the build to fail. At worst, it means that the +wrapper executable will specify file names or paths appropriate for the +build platform. Since those are not appropriate for the host platform, +the uninstalled executables would not operate correctly, even when the +wrapper executable is launched via the appropriate emulation or +API-enhancement (e.g. Wine). Simply install the executables on the +host platform, and execute them there. + + +File: libtool.info, Node: Native MinGW File Name Conversion, Next: Cygwin/Windows File Name Conversion, Prev: File Name Conversion Failure, Up: File name conversion + +15.3.7.2 Native MinGW File Name Conversion +.......................................... + +MSYS is a Unix emulation environment for Windows, and is specifically +designed such that in normal usage it _pretends_ to be MinGW or native +Windows, but understands Unix-style file names and paths, and supports +standard Unix tools and shells. Thus, "native" MinGW builds are +actually an odd sort of cross-compile, from an MSYS Unix emulation +environment "pretending" to be MinGW, to actual native Windows. + + When an MSYS shell launches a native Windows executable (as opposed +to other _MSYS_ executables), it uses a system of heuristics to detect +any command-line arguments that contain file names or paths. It +automatically converts these file names from the MSYS (Unix-like) +format, to the corresponding Windows file name, before launching the +executable. However, this auto-conversion facility is only available +when using the MSYS runtime library. The wrapper executable itself is +a MinGW application (that is, it does not use the MSYS runtime +library). The wrapper executable must set `PATH' to, and call +`_spawnv' with, values that have already been converted from MSYS +format to Windows. Thus, when libtool writes the source code for the +wrapper executable, it must manually convert MSYS paths to Windows +format, so that the Windows values can be hard-coded into the wrapper +executable. + + +File: libtool.info, Node: Cygwin/Windows File Name Conversion, Next: Unix/Windows File Name Conversion, Prev: Native MinGW File Name Conversion, Up: File name conversion + +15.3.7.3 Cygwin/Windows File Name Conversion +............................................ + +Cygwin provides a Unix emulation environment for Windows. As part of +that emulation, it provides a file system mapping that presents the +Windows file system in a Unix-compatible manner. Cygwin also provides +a utility `cygpath' that can be used to convert file names and paths +between the two representations. In a correctly configured Cygwin +installation, `cygpath' is always present, and is in the `PATH'. + + Libtool uses `cygpath' to convert from Cygwin (Unix-style) file names +and paths to Windows format when the build platform is Cygwin and the +host platform is MinGW. + + When the host platform is Cygwin, but the build platform is MSYS or +some Unix system, libtool also uses `cygpath' to convert from Windows +to Cygwin format (after first converting from the build platform format +to Windows format; see *note Native MinGW File Name Conversion:: and +*note Unix/Windows File Name Conversion::). Because the build platform +is not Cygwin, `cygpath' is not (and should not be) in the `PATH'. +Therefore, in this configuration the environment variable `LT_CYGPATH' +is required. *Note LT_CYGPATH::. + + +File: libtool.info, Node: Unix/Windows File Name Conversion, Next: LT_CYGPATH, Prev: Cygwin/Windows File Name Conversion, Up: File name conversion + +15.3.7.4 Unix/Windows File Name Conversion +.......................................... + +Wine (http://www.winehq.org/) provides an interpretation environment for +some Unix platforms in which Windows applications can be executed. It +provides a mapping between the Unix file system and a virtual Windows +file system used by the Windows programs. For the file name conversion +to work, Wine must be installed and properly configured on the build +platform, and the `winepath' application must be in the build +platform's `PATH'. In addition, on 32bit GNU/Linux it is usually +helpful if the binfmt extension is enabled. + + +File: libtool.info, Node: LT_CYGPATH, Next: Cygwin to MinGW Cross, Prev: Unix/Windows File Name Conversion, Up: File name conversion + +15.3.7.5 LT_CYGPATH +................... + +For some cross-compile configurations (where the host platform is +Cygwin), the `cygpath' program is used to convert file names from the +build platform notation to the Cygwin form (technically, this +conversion is from Windows notation to Cygwin notation; the conversion +from the build platform format to Windows notation is performed via +other means). However, because the `cygpath' program is not (and +should not be) in the `PATH' on the build platform, `LT_CYGPATH' must +specify the full build platform file name (that is, the full Unix or +MSYS file name) of the `cygpath' program. + + The reason `cygpath' should not be in the build platform `PATH' is +twofold: first, `cygpath' is usually installed in the same directory as +many other Cygwin executables, such as `sed', `cp', etc. If the build +platform environment had this directory in its `PATH', then these +Cygwin versions of common Unix utilities might be used in preference to +the ones provided by the build platform itself, with deleterious +effects. Second, especially when Cygwin-1.7 or later is used, multiple +Cygwin installations can coexist within the same Windows instance. +Each installation will have separate "mount tables" specified in +`CYGROOT-N/etc/fstab'. These "mount tables" control how that instance +of Cygwin will map Windows file names and paths to Cygwin form. Each +installation's `cygpath' utility automatically deduces the appropriate +`/etc/fstab' file. Since each `CYGROOT-N/etc/fstab' mount table may +specify different mappings, it matters which `cygpath' is used. + + Note that `cygpath' is a Cygwin application; to execute this tool +from Unix requires a working and properly configured Wine installation, +as well as enabling the GNU/Linux `binfmt' extension. Furthermore, the +Cygwin `setup.exe' tool should have been used, via Wine, to properly +install Cygwin into the Wine file system (and registry). + + Unfortunately, Wine support for Cygwin is intermittent. Recent +releases of Cygwin (1.7 and above) appear to require more Windows API +support than Wine provides (as of Wine version 1.2); most Cygwin +applications fail to execute. This includes `cygpath' itself. Hence, +it is best _not_ to use the LT_CYGPATH machinery in libtool when +performing Unix to Cygwin cross-compiles. Similarly, it is best _not_ +to enable the GNU/Linux binfmt support in this configuration, because +while Wine will fail to execute the compiled Cygwin applications, it +will still exit with status zero. This tends to confuse build systems +and test suites (including libtool's own testsuite, resulting in +spurious reported failures). Wine support for the older Cygwin-1.5 +series appears satisfactory, but the Cygwin team no longer supports +Cygwin-1.5. It is hoped that Wine will eventually be improved such that +Cygwin-1.7 will again operate correctly under Wine. Until then, +libtool will report warnings as described in *note File Name Conversion +Failure:: in these scenarios. + + However, `LT_CYGPATH' is also used for the MSYS to Cygwin cross +compile scenario, and operates as expected. + + +File: libtool.info, Node: Cygwin to MinGW Cross, Prev: LT_CYGPATH, Up: File name conversion + +15.3.7.6 Cygwin to MinGW Cross +.............................. + +There are actually three different scenarios that could all +legitimately be called a "Cygwin to MinGW" cross compile. The current +(and standard) definition is when there is a compiler that produces +native Windows libraries and applications, but which itself is a Cygwin +application, just as would be expected in any other cross compile setup. + + However, historically there were two other definitions, which we +will refer to as the _fake_ one, and the _lying_ one. + + In the _fake_ Cygwin to MinGW cross compile case, you actually use a +native MinGW compiler, but you do so from within a Cygwin environment: + + export PATH="/c/MinGW/bin:${PATH}" + configure --build=i686-pc-cygwin \ + --host=mingw32 \ + NM=/c/MinGW/bin/nm.exe + + In this way, the build system "knows" that you are cross compiling, +and the file name conversion logic will be used. However, because the +tools (`mingw32-gcc', `nm', `ar') used are actually native Windows +applications, they will not understand any Cygwin (that is, Unix-like) +absolute file names passed as command line arguments (and, unlike MSYS, +Cygwin does not automatically convert such arguments). However, so +long as only relative file names are used in the build system, and +non-Windows-supported Unix idioms such as symlinks and mount points are +avoided, this scenario should work. + + If you must use absolute file names, you will have to force Libtool +to convert file names for the toolchain in this case, by doing the +following before you run configure: + + export lt_cv_to_tool_file_cmd=func_convert_file_cygwin_to_w32 + + In the _lying_ Cygwin to MinGW cross compile case, you lie to the +build system: + + export PATH="/c/MinGW/bin:${PATH}" + configure --build=i686-pc-mingw32 \ + --host=i686-pc-mingw32 \ + --disable-dependency-tracking + +and claim that the build platform is MinGW, even though you are actually +running under _Cygwin_ and not MinGW. In this case, libtool does _not_ +know that you are performing a cross compile, and thinks instead that +you are performing a native MinGW build. However, as described in +(*note Native MinGW File Name Conversion::), that scenario triggers an +"MSYS to Windows" file name conversion. This, of course, is the wrong +conversion since we are actually running under Cygwin. Also, the +toolchain is expecting Windows file names (not Cygwin) but unless told +so Libtool will feed Cygwin file names to the toolchain in this case. +To force the correct file name conversions in this situation, you +should do the following _before_ running configure: + + export lt_cv_to_host_file_cmd=func_convert_file_cygwin_to_w32 + export lt_cv_to_tool_file_cmd=func_convert_file_cygwin_to_w32 + + Note that this relies on internal implementation details of libtool, +and is subject to change. Also, `--disable-dependency-tracking' is +required, because otherwise the MinGW GCC will generate dependency +files that contain Windows file names. This, in turn, will confuse the +Cygwin `make' program, which does not accept Windows file names: + + Makefile:1: *** target pattern contains no `%'. Stop. + + There have also always been a number of other details required for +the _lying_ case to operate correctly, such as the use of so-called +"identity mounts": + + # CYGWIN-ROOT/etc/fstab + D:/foo /foo some_fs binary 0 0 + D:/bar /bar some_fs binary 0 0 + E:/grill /grill some_fs binary 0 0 + + In this way, top-level directories of each drive are available using +identical names within Cygwin. + + Note that you also need to ensure that the standard Unix directories +(like `/bin', `/lib', `/usr', `/etc') appear in the root of a drive. +This means that you must install Cygwin itself into the `C:/' root +directory (or `D:/', or `E:/', etc)--instead of the recommended +installation into `C:/cygwin/'. In addition, all file names used in +the build system must be relative, symlinks should not be used within +the source or build directory trees, and all `-M*' options to `gcc' +except `-MMD' must be avoided. + + This is quite a fragile setup, but it has been in historical use, +and so is documented here. + + +File: libtool.info, Node: Windows DLLs, Prev: File name conversion, Up: Platform quirks + +15.3.8 Windows DLLs +------------------- + +This topic describes a couple of ways to portably create Windows Dynamic +Link Libraries (DLLs). Libtool knows how to create DLLs using GNU tools +and using Microsoft tools. + + A typical library has a "hidden" implementation with an interface +described in a header file. On just about every system, the interface +could be something like this: + + Example `foo.h': + + #ifndef FOO_H + #define FOO_H + + int one (void); + int two (void); + extern int three; + + #endif /* FOO_H */ + +And the implementation could be something like this: + + Example `foo.c': + + #include "foo.h" + + int one (void) + { + return 1; + } + + int two (void) + { + return three - one (); + } + + int three = 3; + + When using contemporary GNU tools to create the Windows DLL, the +above code will work there too, thanks to its auto-import/auto-export +features. But that is not the case when using older GNU tools or +perhaps more interestingly when using proprietary tools. In those +cases the code will need additional decorations on the interface +symbols with `__declspec(dllimport)' and `__declspec(dllexport)' +depending on whether the library is built or it's consumed and how it's +built and consumed. However, it should be noted that it would have +worked also with Microsoft tools, if only the variable `three' hadn't +been there, due to the fact the Microsoft tools will automatically +import functions (but sadly not variables) and Libtool will +automatically export non-static symbols as described next. + + With Microsoft tools, Libtool digs through the object files that +make up the library, looking for non-static symbols to automatically +export. I.e., Libtool with Microsoft tools tries to mimic the +auto-export feature of contemporary GNU tools. It should be noted that +the GNU auto-export feature is turned off when an explicit +`__declspec(dllexport)' is seen. The GNU tools do this to not make +more symbols visible for projects that have already taken the trouble +to decorate symbols. There is no similar way to limit which symbols +are visible in the code when Libtool is using Microsoft tools. In +order to limit symbol visibility in that case you need to use one of +the options `-export-symbols' or `-export-symbols-regex'. + + No matching help with auto-import is provided by Libtool, which is +why variables must be decorated to import them from a DLL for +everything but contemporary GNU tools. As stated above, functions are +automatically imported by both contemporary GNU tools and Microsoft +tools, but for other proprietary tools the auto-import status of +functions is unknown. + + When the objects that form the library are built, there are generally +two copies built for each object. One copy is used when linking the DLL +and one copy is used for the static library. On Windows systems, a pair +of defines are commonly used to discriminate how the interface symbols +should be decorated. The first define is `-DDLL_EXPORT' which is +automatically provided by Libtool when `libtool' builds the copy of the +object that is destined for the DLL. The second define is +`-DLIBFOO_BUILD' (or similar) which is often added by the package +providing the library and is used when building the library, but not +when consuming the library. + + However, the matching double compile is not performed when consuming +libraries. It is therefore not possible to reliably distinguish if the +consumer is importing from a DLL or if it is going to use a static +library. + + With contemporary GNU tools, auto-import often saves the day, but see +the GNU ld documentation and its `--enable-auto-import' option for some +corner cases when it does not (*note `--enable-auto-import': +(ld)Options.). + + With Microsoft tools you typically get away with always compiling the +code such that variables are expected to be imported from a DLL and +functions are expected to be found in a static library. The tools will +then automatically import the function from a DLL if that is where they +are found. If the variables are not imported from a DLL as expected, +but are found in a static library that is otherwise pulled in by some +function, the linker will issue a warning (LNK4217) that a locally +defined symbol is imported, but it still works. In other words, this +scheme will not work to only consume variables from a library. There is +also a price connected to this liberal use of imports in that an extra +indirection is introduced when you are consuming the static version of +the library. That extra indirection is unavoidable when the DLL is +consumed, but it is not needed when consuming the static library. + + For older GNU tools and other proprietary tools there is no generic +way to make it possible to consume either of the DLL or the static +library without user intervention, the tools need to be told what is +intended. One common assumption is that if a DLL is being built +(`DLL_EXPORT' is defined) then that DLL is going to consume any +dependent libraries as DLLs. If that assumption is made everywhere, it +is possible to select how an end-user application is consuming +libraries by adding a single flag `-DDLL_EXPORT' when a DLL build is +required. This is of course an all or nothing deal, either everything +as DLLs or everything as static libraries. + + To sum up the above, the header file of the foo library needs to be +changed into something like this: + + Modified `foo.h': + + #ifndef FOO_H + #define FOO_H + + #if defined _WIN32 && !defined __GNUC__ + # ifdef LIBFOO_BUILD + # ifdef DLL_EXPORT + # define LIBFOO_SCOPE __declspec (dllexport) + # define LIBFOO_SCOPE_VAR extern __declspec (dllexport) + # endif + # elif defined _MSC_VER + # define LIBFOO_SCOPE + # define LIBFOO_SCOPE_VAR extern __declspec (dllimport) + # elif defined DLL_EXPORT + # define LIBFOO_SCOPE __declspec (dllimport) + # define LIBFOO_SCOPE_VAR extern __declspec (dllimport) + # endif + #endif + #ifndef LIBFOO_SCOPE + # define LIBFOO_SCOPE + # define LIBFOO_SCOPE_VAR extern + #endif + + LIBFOO_SCOPE int one (void); + LIBFOO_SCOPE int two (void); + LIBFOO_SCOPE_VAR int three; + + #endif /* FOO_H */ + + When the targets are limited to contemporary GNU tools and Microsoft +tools, the above can be simplified to the following: + + Simplified `foo.h': + + #ifndef FOO_H + #define FOO_H + + #if defined _WIN32 && !defined __GNUC__ && !defined LIBFOO_BUILD + # define LIBFOO_SCOPE_VAR extern __declspec (dllimport) + #else + # define LIBFOO_SCOPE_VAR extern + #endif + + int one (void); + int two (void); + LIBFOO_SCOPE_VAR int three; + + #endif /* FOO_H */ + + This last simplified version can of course only work when Libtool is +used to build the DLL, as no symbols would be exported otherwise (i.e., +when using Microsoft tools). + + It should be noted that there are various projects that attempt to +relax these requirements by various low level tricks, but they are not +discussed here. Examples are FlexDLL +(http://alain.frisch.fr/flexdll.html) and edll +(http://edll.sourceforge.net/). + + +File: libtool.info, Node: libtool script contents, Next: Cheap tricks, Prev: Platform quirks, Up: Maintaining + +15.4 `libtool' script contents +============================== + +Since version 1.4, the `libtool' script is generated by `configure' +(*note Configuring::). In earlier versions, `configure' achieved this +by calling a helper script called `ltconfig'. From libtool version 0.7 +to 1.0, this script simply set shell variables, then sourced the +libtool backend, `ltmain.sh'. `ltconfig' from libtool version 1.1 +through 1.3 inlined the contents of `ltmain.sh' into the generated +`libtool', which improved performance on many systems. The tests that +`ltconfig' used to perform are now kept in `libtool.m4' where they can +be written using Autoconf. This has the runtime performance benefits +of inlined `ltmain.sh', _and_ improves the build time a little while +considerably easing the amount of raw shell code that used to need +maintaining. + + The convention used for naming variables that hold shell commands for +delayed evaluation, is to use the suffix `_cmd' where a single line of +valid shell script is needed, and the suffix `_cmds' where multiple +lines of shell script *may* be delayed for later evaluation. By +convention, `_cmds' variables delimit the evaluation units with the `~' +character where necessary. + + Here is a listing of each of the configuration variables, and how +they are used within `ltmain.sh' (*note Configuring::): + + -- Variable: AR + The name of the system library archiver. + + -- Variable: CC + The name of the compiler used to configure libtool. This will + always contain the compiler for the current language (*note + Tags::). + + -- Variable: ECHO + An `echo' program that does not interpret backslashes as an escape + character. It may be given only one argument, so due quoting is + necessary. + + -- Variable: LD + The name of the linker that libtool should use internally for + reloadable linking and possibly shared libraries. + + -- Variable: LTCC + -- Variable: LTCFLAGS + The name of the C compiler and C compiler flags used to configure + libtool. + + -- Variable: NM + The name of a BSD- or MS-compatible program that produces listings + of global symbols. For BSD `nm', the symbols should be in one the + following formats: + + ADDRESS C GLOBAL-VARIABLE-NAME + ADDRESS D GLOBAL-VARIABLE-NAME + ADDRESS T GLOBAL-FUNCTION-NAME + + For MS `dumpbin', the symbols should be in one of the following + formats: + + COUNTER SIZE UNDEF notype External | GLOBAL-VAR + COUNTER ADDRESS SECTION notype External | GLOBAL-VAR + COUNTER ADDRESS SECTION notype () External | GLOBAL-FUNC + + The SIZE of the global variables are not zero and the SECTION of + the global functions are not "UNDEF". Symbols in "pick any" + sections ("pick any" appears in the section header) are not global + either. + + -- Variable: RANLIB + Set to the name of the `ranlib' program, if any. + + -- Variable: allow_undefined_flag + The flag that is used by `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 `unsupported' if there + is no way to generate a shared library with references to symbols + that aren't defined in that library. + + -- Variable: always_export_symbols + Whether libtool should automatically generate a list of exported + symbols using `export_symbols_cmds' before linking an archive. + Set to `yes' or `no'. Default is `no'. + + -- Variable: archive_cmds + -- Variable: archive_expsym_cmds + -- Variable: old_archive_cmds + Commands used to create shared libraries, shared libraries with + `-export-symbols' and static libraries, respectively. + + -- Variable: archiver_list_spec + Specify filename containing input files for `AR'. + + -- Variable: old_archive_from_new_cmds + If the shared library depends on a static library, + `old_archive_from_new_cmds' contains the commands used to create + that static library. If this variable is not empty, + `old_archive_cmds' is not used. + + -- Variable: 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, + `old_archive_from_expsyms_cmds' contains the commands needed to + create that static library. When these commands are executed, the + variable `soname' contains the name of the shared library in + question, and the `$objdir/$newlib' contains the path of the + static library these commands should build. After executing these + commands, libtool will proceed to link against `$objdir/$newlib' + instead of `soname'. + + -- Variable: lock_old_archive_extraction + Set to `yes' if the extraction of a static library requires locking + the library file. This is required on Darwin. + + -- Variable: build + -- Variable: build_alias + -- Variable: build_os + Set to the specified and canonical names of the system that + libtool was built on. + + -- Variable: build_libtool_libs + Whether libtool should build shared libraries on this system. Set + to `yes' or `no'. + + -- Variable: build_old_libs + Whether libtool should build static libraries on this system. Set + to `yes' or `no'. + + -- Variable: compiler_c_o + Whether the compiler supports the `-c' and `-o' options + simultaneously. Set to `yes' or `no'. + + -- Variable: compiler_needs_object + Whether the compiler has to see an object listed on the command + line in order to successfully invoke the linker. If `no', then a + set of convenience archives or a set of object file names can be + passed via linker-specific options or linker scripts. + + -- Variable: dlopen_support + Whether `dlopen' is supported on the platform. Set to `yes' or + `no'. + + -- Variable: dlopen_self + Whether it is possible to `dlopen' the executable itself. Set to + `yes' or `no'. + + -- Variable: dlopen_self_static + Whether it is possible to `dlopen' the executable itself, when it + is linked statically (`-all-static'). Set to `yes' or `no'. + + -- Variable: exclude_expsyms + List of symbols that should not be listed in the preloaded symbols. + + -- Variable: export_dynamic_flag_spec + Compiler link flag that allows a dlopened shared library to + reference symbols that are defined in the program. + + -- Variable: export_symbols_cmds + Commands to extract exported symbols from `libobjs' to the file + `export_symbols'. + + -- Variable: extract_expsyms_cmds + Commands to extract the exported symbols list from a shared + library. These commands are executed if there is no file + `$objdir/$soname-def', and should write the names of the exported + symbols to that file, for the use of + `old_archive_from_expsyms_cmds'. + + -- Variable: 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 where + `shlibpath_overrides_runpath' is not `yes', so `fast_install' will + be set to `needless' in this case. If `fast_install' set to + `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 `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 `yes' or + `needless', depending on platform and configuration flags, and it + can be turned from `yes' to `no' with the configure flag + `--disable-fast-install'. + + On some systems, the linker always hardcodes paths to dependent + libraries into the output. In this case, `fast_install' is never + set to `yes', and relinking at install time is triggered. This + also means that `DESTDIR' installation does not work as expected. + + -- Variable: file_magic_glob + How to find potential files when `deplibs_check_method' is + `file_magic'. `file_magic_glob' is a `sed' expression, and the + `sed' instance is fed potential file names that are transformed by + the `file_magic_glob' expression. Useful when the shell does not + support the shell option `nocaseglob', making `want_nocaseglob' + inappropriate. Normally disabled (i.e. `file_magic_glob' is + empty). + + -- Variable: finish_cmds + Commands to tell the dynamic linker how to find shared libraries + in a specific directory. + + -- Variable: finish_eval + Same as `finish_cmds', except the commands are not displayed. + + -- Variable: global_symbol_pipe + A pipeline that takes the output of `NM', and produces a listing of + raw symbols followed by their C names. For example: + + $ eval "$NM progname | $global_symbol_pipe" + D SYMBOL1 C-SYMBOL1 + T SYMBOL2 C-SYMBOL2 + C SYMBOL3 C-SYMBOL3 + ... + $ + + The first column contains the symbol type (used to tell data from + code) but its meaning is system dependent. + + -- Variable: global_symbol_to_cdecl + A pipeline that translates the output of `global_symbol_pipe' into + proper C declarations. Since some platforms, such as HP/UX, have + linkers that differentiate code from data, data symbols are + declared as data, and code symbols are declared as functions. + + -- Variable: hardcode_action + Either `immediate' or `relink', depending on whether shared + library paths can be hardcoded into executables before they are + installed, or if they need to be relinked. + + -- Variable: hardcode_direct + Set to `yes' or `no', depending on whether the linker hardcodes + directories if a library is directly specified on the command line + (such as `DIR/libNAME.a') when `hardcode_libdir_flag_spec' is + specified. + + -- Variable: hardcode_direct_absolute + Some architectures hardcode "absolute" library directories that + can not be overridden by `shlibpath_var' when `hardcode_direct' is + `yes'. In that case set `hardcode_direct_absolute' to `yes', or + otherwise `no'. + + -- Variable: 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 `yes' or `no'. + + -- Variable: hardcode_libdir_flag_spec + Flag to hardcode a `libdir' variable into a binary, so that the + dynamic linker searches `libdir' for shared libraries at runtime. + If it is empty, libtool will try to use some other hardcoding + mechanism. + + -- Variable: hardcode_libdir_separator + If the compiler only accepts a single `hardcode_libdir_flag', then + this variable contains the string that should separate multiple + arguments to that flag. + + -- Variable: hardcode_minus_L + Set to `yes' or `no', depending on whether the linker hardcodes + directories specified by `-L' flags into the resulting executable + when `hardcode_libdir_flag_spec' is specified. + + -- Variable: hardcode_shlibpath_var + Set to `yes' or `no', depending on whether the linker hardcodes + directories by writing the contents of `$shlibpath_var' into the + resulting executable when `hardcode_libdir_flag_spec' is + specified. Set to `unsupported' if directories specified by + `$shlibpath_var' are searched at run time, but not at link time. + + -- Variable: host + -- Variable: host_alias + -- Variable: host_os + Set to the specified and canonical names of the system that + libtool was configured for. + + -- Variable: include_expsyms + List of symbols that must always be exported when using + `export_symbols'. + + -- Variable: inherit_rpath + Whether the linker adds runtime paths of dependency libraries to + the runtime path list, requiring libtool to relink the output when + installing. Set to `yes' or `no'. Default is `no'. + + -- Variable: install_override_mode + Permission mode override for installation of shared libraries. If + the runtime linker fails to load libraries with wrong permissions, + then it may fail to execute programs that are needed during + installation, because these need the library that has just been + installed. In this case, it is necessary to pass the mode to + `install' with `-m INSTALL_OVERRIDE_MODE'. + + -- Variable: libext + The standard old archive suffix (normally `a'). + + -- Variable: libname_spec + The format of a library name prefix. On all Unix systems, static + libraries are called `libNAME.a', but on some systems (such as + OS/2 or MS-DOS), the library is just called `NAME.a'. + + -- Variable: 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 `-lNAME'. + + -- Variable: link_all_deplibs + Whether libtool must link a program against all its dependency + libraries. Set to `yes' or `no'. Default is `unknown', which is + a synonym for `yes'. + + -- Variable: link_static_flag + Linker flag (passed through the C compiler) used to prevent dynamic + linking. + + -- Variable: macro_version + -- Variable: macro_revision + The release and revision from which the libtool.m4 macros were + taken. This is used to ensure that macros and `ltmain.sh' + correspond to the same Libtool version. + + -- Variable: max_cmd_len + The approximate longest command line that can be passed to `$SHELL' + without being truncated, as computed by `LT_CMD_MAX_LEN'. + + -- Variable: need_lib_prefix + Whether we can `dlopen' modules without a `lib' prefix. Set to + `yes' or `no'. By default, it is `unknown', which means the same + as `yes', but documents that we are not really sure about it. + `no' means that it is possible to `dlopen' a module without the + `lib' prefix. + + -- Variable: need_version + Whether versioning is required for libraries, i.e. whether the + dynamic linker requires a version suffix for all libraries. Set + to `yes' or `no'. By default, it is `unknown', which means the + same as `yes', but documents that we are not really sure about it. + + -- Variable: need_locks + Whether files must be locked to prevent conflicts when compiling + simultaneously. Set to `yes' or `no'. + + -- Variable: nm_file_list_spec + Specify filename containing input files for `NM'. + + -- Variable: no_builtin_flag + Compiler flag to disable builtin functions that conflict with + declaring external global symbols as `char'. + + -- Variable: no_undefined_flag + The flag that is used by `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. + + -- Variable: objdir + The name of the directory that contains temporary libtool files. + + -- Variable: objext + The standard object file suffix (normally `o'). + + -- Variable: pic_flag + Any additional compiler flags for building library object files. + + -- Variable: postinstall_cmds + -- Variable: old_postinstall_cmds + Commands run after installing a shared or static library, + respectively. + + -- Variable: postuninstall_cmds + -- Variable: old_postuninstall_cmds + Commands run after uninstalling a shared or static library, + respectively. + + -- Variable: postlink_cmds + Commands necessary for finishing linking programs. `postlink_cmds' + are executed immediately after the program is linked. Any + occurrence of the string `@OUTPUT@' in `postlink_cmds' is replaced + by the name of the created executable (i.e. not the wrapper, if a + wrapper is generated) prior to execution. Similarly, + `@TOOL_OUTPUT@' is replaced by the toolchain format of `@OUTPUT@'. + Normally disabled (i.e. `postlink_cmds' empty). + + -- Variable: reload_cmds + -- Variable: reload_flag + Commands to create a reloadable object. Set `reload_cmds' to + `false' on systems that cannot create reloadable objects. + + -- Variable: runpath_var + The environment variable that tells the linker which directories to + hardcode in the resulting executable. + + -- Variable: 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 `fast_install'. The default value is `unknown', which is + equivalent to `no'. + + -- Variable: shlibpath_var + The environment variable that tells the dynamic linker where to + find shared libraries. + + -- Variable: soname_spec + The name coded into shared libraries, if different from the real + name of the file. + + -- Variable: striplib + -- Variable: old_striplib + Command to strip a shared (`striplib') or static (`old_striplib') + library, respectively. If these variables are empty, the strip + flag in the install mode will be ignored for libraries (*note + Install mode::). + + -- Variable: 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. + + -- Variable: 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 + `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 `-L' also augment the search path. + + -- Variable: thread_safe_flag_spec + Linker flag (passed through the C compiler) used to generate + thread-safe libraries. + + -- Variable: to_host_file_cmd + If the toolchain is not native to the build platform (e.g. if you + are using MSYS to drive the scripting, but are using the MinGW + native Windows compiler) this variable describes how to convert + file names from the format used by the build platform to the + format used by host platform. Normally set to + `func_convert_file_noop', libtool will autodetect most cases in + which other values should be used. On rare occasions, it may be + necessary to override the autodetected value (*note Cygwin to + MinGW Cross::). + + -- Variable: to_tool_file_cmd + If the toolchain is not native to the build platform (e.g. if you + are using some Unix to drive the scripting together with a Windows + toolchain running in Wine) this variable describes how to convert + file names from the format used by the build platform to the + format used by the toolchain. Normally set to + `func_convert_file_noop'. + + -- Variable: version_type + The library version numbering type. One of `libtool', + `freebsd-aout', `freebsd-elf', `irix', `linux', `osf', `sunos', + `windows', or `none'. + + -- Variable: want_nocaseglob + Find potential files using the shell option `nocaseglob', when + `deplibs_check_method' is `file_magic'. Normally set to `no'. Set + to `yes' to enable the `nocaseglob' shell option when looking for + potential file names in a case-insensitive manner. + + -- Variable: whole_archive_flag_spec + Compiler flag to generate shared objects from convenience archives. + + -- Variable: wl + The C compiler flag that allows libtool to pass a flag directly to + the linker. Used as: `${wl}SOME-FLAG'. + + Variables ending in `_cmds' or `_eval' contain a `~'-separated list +of commands that are `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 `_spec' are `eval'ed before being used by +libtool. + + +File: libtool.info, Node: Cheap tricks, Prev: libtool script contents, Up: Maintaining + +15.5 Cheap tricks +================= + +Here are a few tricks that you can use in order to make maintainership +easier: + + * When people report bugs, ask them to use the `--config', + `--debug', or `--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. + + * Rather than reconfiguring libtool every time I make a change to + `ltmain.in', I keep a permanent `libtool' script in my `PATH', + which sources `ltmain.in' directly. + + The following steps describe how to create such a script, where + `/home/src/libtool' is the directory containing the libtool source + tree, `/home/src/libtool/libtool' is a libtool script that has been + configured for your platform, and `~/bin' is a directory in your + `PATH': + + trick$ cd ~/bin + trick$ sed 's%^\(macro_version=\).*$%\1@VERSION@%; + s%^\(macro_revision=\).*$%\1@package_revision@%; + /^# ltmain\.sh/q' /home/src/libtool/libtool > libtool + trick$ echo '. /home/src/libtool/ltmain.in' >> libtool + trick$ chmod +x libtool + trick$ libtool --version + ltmain.sh (GNU @PACKAGE@@TIMESTAMP@) @VERSION@ + + Copyright (C) 2011 Free Software Foundation, Inc. + This is free software; see the source for copying conditions. There is NO + warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. + trick$ + + The output of the final `libtool --version' command shows that the +`ltmain.in' script is being used directly. Now, modify `~/bin/libtool' +or `/home/src/libtool/ltmain.in' directly in order to test new changes +without having to rerun `configure'. + -- cgit v1.2.3