diff options
| author | Leo Tenenbaum <pommicket@gmail.com> | 2018-08-20 21:12:06 -0400 |
|---|---|---|
| committer | Leo Tenenbaum <pommicket@gmail.com> | 2018-08-20 21:12:06 -0400 |
| commit | 63e87c2d0c9d263f14c77b68f85c67d46ece82a9 (patch) | |
| tree | 6260365cbf7d24f37d27669e8538227fcb72e243 /gtk+-mingw/share/info/libtool.info-1 | |
| parent | a4460f6d9453bbd7e584937686449cef3e19f052 (diff) | |
Diffstat (limited to 'gtk+-mingw/share/info/libtool.info-1')
| -rw-r--r-- | gtk+-mingw/share/info/libtool.info-1 | 6698 |
1 files changed, 0 insertions, 6698 deletions
diff --git a/gtk+-mingw/share/info/libtool.info-1 b/gtk+-mingw/share/info/libtool.info-1 deleted file mode 100644 index 6d16648..0000000 --- a/gtk+-mingw/share/info/libtool.info-1 +++ /dev/null @@ -1,6698 +0,0 @@ -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 <bug-libtool@gnu.org>. - - 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 <ltdl.h> - - 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 <ltdl.h> - -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 -<bug-libtool@gnu.org>. - - -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 -<bug-libtool@gnu.org> 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 -<libtool@gnu.org>, 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 <badger@prtr-13.ucsc.edu>. 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'. - |