This is libtool.info, produced by makeinfo version 3.12k from 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 * libtoolize: (libtool)Invoking libtoolize. Adding libtool support. END-INFO-DIR-ENTRY This file documents GNU Libtool 1.3.4 Copyright (C) 1996-1999 Free Software Foundation, Inc. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that this permission notice may be stated in a translation approved by the Foundation.  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 1.3.4. *Note Reporting bugs::, for information on how to report problems with libtool. * Menu: * Introduction:: What the heck is libtool? * Libtool paradigm:: How libtool's view of libraries is different. * Using libtool:: Example of using libtool to build libraries. * Invoking libtool:: Running the `libtool' script. * Integrating libtool:: Using libtool in your own packages. * Versioning:: Using library interface versions. * Library tips:: Tips for library interface design. * Inter-library dependencies:: Libraries that depend on other libraries. * Dlopened modules:: `dlopen'ing libtool-created libraries. * Using libltdl:: Libtool's portable `dlopen' wrapper library. * Other languages:: Using libtool without a C compiler. * Troubleshooting:: When libtool doesn't work as advertised. * Maintaining:: Information used by the libtool maintainer. * Index:: Full index. Introduction * Motivation:: Why does GNU need a libtool? * Issues:: The problems that need to be addressed. * Other implementations:: How other people have solved these issues. * Postmortem:: Learning from past difficulties. Using libtool * Creating object files:: Compiling object files for libraries. * Linking libraries:: Creating libraries from object files. * Linking executables:: Linking object files against libtool libraries. * Debugging executables:: Running GDB on libtool-generated programs. * Installing libraries:: Making libraries available to users. * Installing executables:: Making programs available to users. * Static libraries:: When shared libraries are not wanted. Invoking `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 executables and libraries. Integrating libtool with your package * 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 * Invoking ltconfig:: `ltconfig' command line options. * ltconfig example:: Manually configuring a `libtool'. * AM_PROG_LIBTOOL:: Configuring `libtool' in `configure.in'. Including libtool in your package * Invoking libtoolize:: `libtoolize' command line options. * Autoconf .o macros:: Autoconf macros that set object file names. Library interface versions * Interfaces:: What are library interfaces? * Libtool versioning:: Libtool's versioning system. * Updating version info:: Changing version information before releases. * Release numbers:: Breaking binary compatibility for aesthetics. Tips for interface design * C header files:: How to write portable include files. Dlopened modules * Building modules:: Creating dlopenable objects and libraries. * Dlpreopening:: Dlopening that works on static platforms. * Finding the dlname:: Choosing the right file to `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. * Distributing libltdl:: How to distribute libltdl with your package. Using libtool with other languages * C++ libraries:: Troubleshooting * Libtool test suite:: Libtool's self-tests. * Reporting bugs:: How to report problems with libtool. The libtool test suite * Test descriptions:: The contents of the test suite. * When tests fail:: What to do when a test fails. Maintenance notes for libtool * New ports:: How to port libtool to new systems. * Tested platforms:: When libtool was last tested. * Platform quirks:: Information about different library systems. * libtool script contents:: Configuration information that libtool uses. * Cheap tricks:: Making libtool maintainership easier. Porting libtool to new systems * Information sources:: Where to find relevant documentation * Porting inter-library dependencies:: Implementation details explained Platform quirks * References:: Finding more information. * Compilers:: Creating object files from source files. * Reloadable objects:: Binding object files together. * Archivers:: Programs that create static archives.  File: libtool.info, Node: Introduction, Next: Libtool paradigm, Prev: Top, Up: Top Introduction ************ In the past, if a source code package developer wanted to take advantage of the power of shared libraries, he needed to write custom support code for each platform on which his package ran. He also had to design a configuration interface so that the package installer could choose what sort of libraries were built. GNU Libtool simplifies the developer's job by encapsulating both the platform-specific dependencies, and the user interface, in a single script. GNU Libtool is designed so that the complete functionality of each host type is available via a generic interface, but nasty quirks are hidden from the programmer. GNU Libtool's consistent interface is reassuring... 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 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 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 which 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 which 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 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 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 which 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 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 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.o' or `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 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, `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 by using separate library object files (which end in `.lo' instead of `.o'). On systems without shared libraries (or without special PIC compiler flags), these library object files are identical to "standard" object files. To create library object files for `foo.c' and `hello.c', simply invoke libtool with the standard compilation command as arguments (*note Compile mode::): a23$ libtool gcc -g -O -c foo.c gcc -g -O -c foo.c echo timestamp > foo.lo a23$ libtool gcc -g -O -c hello.c gcc -g -O -c hello.c echo timestamp > hello.lo a23$ Note that libtool creates two files for each invocation. The `.lo' file is a library object, which may be built into a shared library, and the `.o' file is a standard object file. On `a23', the library objects are just timestamps, because only static libraries are supported. On shared library systems, libtool automatically inserts the PIC generation flags into the compilation command, so that the library object and the standard object differ: burger$ libtool gcc -g -O -c foo.c gcc -g -O -c -fPIC -DPIC foo.c mv -f foo.o foo.lo gcc -g -O -c foo.c >/dev/null 2>&1 burger$ libtool gcc -g -O -c hello.c gcc -g -O -c -fPIC -DPIC hello.c mv -f hello.o hello.lo gcc -g -O -c hello.c >/dev/null 2>&1 burger$ Notice that the second run of GCC has its output discarded. This is done so that compiler warnings aren't annoyingly duplicated.  File: libtool.info, Node: Linking libraries, Next: Linking executables, Prev: Creating object files, Up: Using libtool 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 library name differs from the standard name (it has a `.la' suffix instead of a `.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 gcc -g -O -o libhello.la foo.o hello.o libtool: cannot build libtool library `libhello.la' from non-libtool \ objects a23$ Aha! Libtool caught a common error... trying to build a library from standard objects instead of library objects. This doesn't matter for static libraries, but on shared library systems, it is of great importance. So, let's try again, this time with the library object files. Remember also that we need to add `-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 gcc -g -O -o libhello.la foo.lo hello.lo \ -rpath /usr/local/lib -lm mkdir .libs ar cru .libs/libhello.a foo.o hello.o ranlib .libs/libhello.a creating libhello.la a23$ Now, let's try the same trick on the shared library platform: burger$ libtool gcc -g -O -o libhello.la foo.lo hello.lo \ -rpath /usr/local/lib -lm mkdir .libs ld -Bshareable -o .libs/libhello.so.0.0 foo.lo hello.lo -lm ar cru .libs/libhello.a foo.o hello.o ranlib .libs/libhello.a creating 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. ---------- 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 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 gcc -g -O -o hell main.o libhello.la -lm 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. On `burger' the situation is different: burger$ libtool gcc -g -O -o hell main.o libhello.la -lm 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 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 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? Since libtool created a wrapper script, you should use libtool to install it and debug it too. However, since the program does not depend on any uninstalled libtool library, it is probably usable even without the wrapper script. Libtool could probably be made smarter to avoid the creation of the wrapper script in this case, but this is left as an exercise for the reader. Notice that the executable, `hell', was actually created in the `.libs' subdirectory. Then, a wrapper script was created in the current directory. 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. ---------- 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.  File: libtool.info, Node: Debugging executables, Next: Installing libraries, Prev: Linking executables, Up: Using libtool 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 trick:/home/src/libtool/demo$ gdb .libs/hell GDB is free software and you are welcome to distribute copies of it under certain conditions; type "show copying" to see the conditions. There is no warranty for GDB; type "show warranty" for details. GDB 4.16 (i386-unknown-netbsd), (C) 1996 Free Software Foundation, Inc. (gdb) 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.2' 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 gdb hell GDB is free software and you are welcome to distribute copies of it under certain conditions; type "show copying" to see the conditions. There is no warranty for GDB; type "show warranty" for details. GDB 4.16 (i386-unknown-netbsd), (C) 1996 Free Software Foundation, Inc. (gdb) 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 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 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 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 accidentally strip the libraries, though, or they will be unusable.  File: libtool.info, Node: Installing executables, Next: Static libraries, Prev: Installing libraries, Up: Using libtool 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 install -c hell /usr/local/bin/hell install -c hell /usr/local/bin/hell a23# On shared library systems, libtool just ignores the wrapper script and installs the correct binary: burger# libtool 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 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 programs. You can create a "convenience library" out of those objects, and link programs with the library, instead of listing all object files for every program. This technique is often used to overcome GNU automake's lack of support for linking object files built from sources in other directories, because it supports linking with libraries from other directories. This limitation applies to GNU automake up to release 1.4; newer releases should support sources in other directories. If you just want to link this convenience library into programs, then you could just ignore libtool entirely, and use the old `ar' and `ranlib' commands (or the corresponding GNU automake `_LIBRARIES' rules). You can even install a convenience library (but you probably don't want to) using libtool: burger$ libtool ./install-sh -c libhello.a /local/lib/libhello.a ./install-sh -c libhello.a /local/lib/libhello.a ranlib /local/lib/libhello.a burger$ 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 create a libtool convenience library that can be used to create other libtool libraries, even shared ones. Just like in the static case, the library behaves as an alias to a set of object files and dependency libraries, but in this case the object files are suitable for inclusion in shared libraries. But be careful not to link a single convenience library, directly or indirectly, into a single program or library, otherwise you may get errors about symbol redefinitions. When GNU automake is used, you should use `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 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'. `--help' Display a help message and exit. If `--mode=MODE' is specified, then detailed help for MODE is displayed. `--mode=MODE' Use MODE as the operation mode. By default, the operation mode is inferred from the MODE-ARGS. If MODE is specified, it must be 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. `finish' Complete the installation of libtool libraries on the system. `install' Install libraries or executables. `link' Create a library or an executable. `uninstall' Delete libraries or executables. `--version' Print libtool version information and exit. 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 executables and libraries.  File: libtool.info, Node: Compile mode, Next: Link mode, Up: Invoking libtool 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. If the `-static' option is given, then a `.o' file is built, even if libtool was configured with `--disable-static'. 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 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.  File: libtool.info, Node: Link mode, Next: Execute mode, Prev: Compile mode, Up: Invoking libtool 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. `-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. `-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' 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 LT_PRELOADED_SYMBOLS (*note Dlpreopening::). If FILE is `self', the symbols of the program itself will be added to LT_PRELOADED_SYMBOLS. If FILE is `force' libtool will make sure that LT_PRELOADED_SYMBOLS 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-undefined' Declare that OUTPUT-FILE does not depend on any other libraries. Some platforms cannot create shared libraries that depend on other libraries (*note Inter-library dependencies::). `-o OUTPUT-FILE' Create OUTPUT-FILE from the specified objects and libraries. `-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. `-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. `-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. `-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. 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 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 Install mode ============ In "install" mode, libtool interprets MODE-ARGS as an installation command beginning with `cp', or a BSD-compatible `install' program. The rest of the MODE-ARGS are interpreted as arguments to that 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 Finish mode =========== "Finish" mode helps system administrators install libtool libraries so that they can be located and linked into user programs. Each MODE-ARG is interpreted as the name of a library directory. Running this command may require superuser privileges, so the `--dry-run' option may be useful.  File: libtool.info, Node: Uninstall mode, Prev: Finish mode, Up: Invoking libtool 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: Integrating libtool, Next: Versioning, Prev: Invoking libtool, Up: Top Integrating libtool with your package ************************************* This chapter describes how to integrate libtool with your packages so that your users can install hassle-free shared libraries. * Menu: * Makefile rules:: Writing `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: Makefile rules, Next: Using Automake, Up: Integrating libtool 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 1.2, and you don't know how to incorporate libtool into your package you need to do one of the following: 1. Download Automake (version 1.2 or later) 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 `demo' subdirectory of the libtool distribution... note especially that it was automatically generated from the `Makefile.am' by Automake).