1 \input texinfo @c -*-texinfo-*-
3 @setfilename libtool.info
5 @c For double-sided printing, uncomment:
6 @c @setchapternewpage odd
10 @set BUGADDR the Libtool bug reporting address @email{bug-libtool@@gnu.org}
11 @set MAILLIST the Libtool mailing list @email{libtool@@gnu.org}
14 @dircategory GNU programming tools
16 * Libtool: (libtool). Generic shared library support script.
19 @dircategory Individual utilities
21 * libtool-invocation: (libtool)Invoking libtool.
22 Running the @code{libtool} script.
23 * libtoolize: (libtool)Invoking libtoolize. Adding libtool support.
27 This file documents GNU Libtool @value{VERSION}
29 Copyright (C) 1996-2011 Free Software Foundation, Inc.
31 Permission is granted to copy, distribute and/or modify this document
32 under the terms of the GNU Free Documentation License, Version 1.3
33 or any later version published by the Free Software Foundation;
34 with no Invariant Sections, with no Front-Cover Texts,
35 and with no Back-Cover Texts. A copy of the license is included in
36 the section entitled "GNU Free Documentation License".
39 Permission is granted to process this file through TeX and print the
40 results, provided the printed document carries copying permission notice
41 identical to this one except for the removal of this paragraph
48 @subtitle For version @value{VERSION}, @value{UPDATED}
49 @author Gordon Matzigkeit
50 @author Alexandre Oliva
52 @author Gary V. Vaughan
55 @vskip 0pt plus 1filll
56 Copyright @copyright{} 1996-2011 Free Software Foundation, Inc.
58 Permission is granted to copy, distribute and/or modify this document
59 under the terms of the GNU Free Documentation License, Version 1.3
60 or any later version published by the Free Software Foundation;
61 with no Invariant Sections, with no Front-Cover Texts,
62 and with no Back-Cover Texts. A copy of the license is included in
63 the section entitled "GNU Free Documentation License".
67 @c Put everything in one index (arbitrarily chosen to be the concept index).
76 @node Top, Introduction, (dir), (dir)
77 @comment node-name, next, previous, up
78 @top Shared library support for GNU
80 This file documents GNU Libtool, a script that allows package developers
81 to provide generic shared library support. This edition documents
82 version @value{VERSION}.
84 @xref{Reporting bugs}, for information on how to report problems with
88 * Introduction:: What the heck is libtool?
89 * Libtool paradigm:: How libtool's view of libraries is different.
90 * Using libtool:: Example of using libtool to build libraries.
91 * Invoking libtool:: Running the @code{libtool} script.
92 * Integrating libtool:: Using libtool in your own packages.
93 * Other languages:: Using libtool without a C compiler.
94 * Versioning:: Using library interface versions.
95 * Library tips:: Tips for library interface design.
96 * Inter-library dependencies:: Libraries that depend on other libraries.
97 * Dlopened modules:: @code{dlopen}ing libtool-created libraries.
98 * Using libltdl:: Libtool's portable @code{dlopen} wrapper library.
99 * Trace interface:: Libtool's trace interface.
100 * FAQ:: Frequently Asked Questions
101 * Troubleshooting:: When libtool doesn't work as advertised.
102 * Maintaining:: Information used by the libtool maintainer.
103 * GNU Free Documentation License:: License for this manual.
104 * Combined Index:: Full index.
107 --- The Detailed Node Listing ---
111 * Motivation:: Why does GNU need a libtool?
112 * Issues:: The problems that need to be addressed.
113 * Other implementations:: How other people have solved these issues.
114 * Postmortem:: Learning from past difficulties.
118 * Creating object files:: Compiling object files for libraries.
119 * Linking libraries:: Creating libraries from object files.
120 * Linking executables:: Linking object files against libtool libraries.
121 * Debugging executables:: Running GDB on libtool-generated programs.
122 * Installing libraries:: Making libraries available to users.
123 * Installing executables:: Making programs available to users.
124 * Static libraries:: When shared libraries are not wanted.
128 * Wrapper executables:: Wrapper executables for some platforms.
130 Invoking @command{libtool}
132 * Compile mode:: Creating library object files.
133 * Link mode:: Generating executables and libraries.
134 * Execute mode:: Debugging libtool-generated programs.
135 * Install mode:: Making libraries and executables public.
136 * Finish mode:: Completing a library installation.
137 * Uninstall mode:: Removing installed executables and libraries.
138 * Clean mode:: Removing uninstalled executables and libraries.
140 Integrating libtool with your package
142 * Autoconf macros:: Autoconf macros exported by libtool.
143 * Makefile rules:: Writing @file{Makefile} rules for libtool.
144 * Using Automake:: Automatically supporting libtool.
145 * Configuring:: Configuring libtool for a host system.
146 * Distributing:: What files to distribute with your package.
147 * Static-only libraries:: Sometimes shared libraries are just a pain.
151 * LT_INIT:: Configuring @code{libtool} in @file{configure.ac}.
152 * Configure notes:: Platform-specific notes for configuration.
154 Including libtool in your package
156 * Invoking libtoolize:: @code{libtoolize} command line options.
157 * Autoconf and LTLIBOBJS:: Autoconf automates LTLIBOBJS generation.
159 Using libtool with other languages
161 * C++ libraries:: Writing libraries for C++
164 Library interface versions
166 * Interfaces:: What are library interfaces?
167 * Libtool versioning:: Libtool's versioning system.
168 * Updating version info:: Changing version information before releases.
169 * Release numbers:: Breaking binary compatibility for aesthetics.
171 Tips for interface design
173 * C header files:: How to write portable include files.
177 * Building modules:: Creating dlopenable objects and libraries.
178 * Dlpreopening:: Dlopening that works on static platforms.
179 * Linking with dlopened modules:: Using dlopenable modules in libraries.
180 * Finding the dlname:: Choosing the right file to @code{dlopen}.
181 * Dlopen issues:: Unresolved problems that need your attention.
185 * Libltdl interface:: How to use libltdl in your programs.
186 * Modules for libltdl:: Creating modules that can be @code{dlopen}ed.
187 * Thread Safety in libltdl:: Registering callbacks for multi-thread safety.
188 * User defined module data:: Associating data with loaded modules.
189 * Module loaders for libltdl:: Creating user defined module loaders.
190 * Distributing libltdl:: How to distribute libltdl with your package.
192 Frequently Asked Questions about libtool
194 * Stripped link flags:: Dropped flags when creating a library
198 * Libtool test suite:: Libtool's self-tests.
199 * Reporting bugs:: How to report problems with libtool.
201 The libtool test suite
203 * Test descriptions:: The contents of the old test suite.
204 * When tests fail:: What to do when a test fails.
206 Maintenance notes for libtool
208 * New ports:: How to port libtool to new systems.
209 * Tested platforms:: When libtool was last tested.
210 * Platform quirks:: Information about different library systems.
211 * libtool script contents:: Configuration information that libtool uses.
212 * Cheap tricks:: Making libtool maintainership easier.
214 Porting libtool to new systems
216 * Information sources:: Where to find relevant documentation
217 * Porting inter-library dependencies:: Implementation details explained
221 * References:: Finding more information.
222 * Compilers:: Creating object files from source files.
223 * Reloadable objects:: Binding object files together.
224 * Multiple dependencies:: Removing duplicate dependent libraries.
225 * Archivers:: Programs that create static archives.
226 * Cross compiling:: Issues that arise when cross compiling.
227 * File name conversion:: Converting file names between platforms.
228 * Windows DLLs:: Windows header defines.
232 * File Name Conversion Failure:: What happens when file name conversion fails
233 * Native MinGW File Name Conversion:: MSYS file name conversion idiosyncrasies
234 * Cygwin/Windows File Name Conversion:: Using @command{cygpath} to convert Cygwin file names
235 * Unix/Windows File Name Conversion:: Using Wine to convert Unix paths
236 * LT_CYGPATH:: Invoking @command{cygpath} from other environments
237 * Cygwin to MinGW Cross:: Other notes concerning MinGW cross
245 @chapter Introduction
247 In the past, if you were a source code package developer and wanted to
248 take advantage of the power of shared libraries, you needed to write
249 custom support code for each platform on which your package ran. You
250 also had to design a configuration interface so that the package
251 installer could choose what sort of libraries were built.
253 GNU Libtool simplifies your job by encapsulating both the
254 platform-specific dependencies, and the user interface, in a single
255 script. GNU Libtool is designed so that the complete functionality of
256 each host type is available via a generic interface, but nasty quirks
257 are hidden from the programmer.
259 GNU Libtool's consistent interface is reassuring@dots{} users don't need
260 to read obscure documentation in order to have their favorite source
261 package build shared libraries. They just run your package
262 @code{configure} script (or equivalent), and libtool does all the dirty
265 There are several examples throughout this document. All assume the
266 same environment: we want to build a library, @file{libhello}, in a
269 @file{libhello} could be a shared library, a static library, or
270 both@dots{} whatever is available on the host system, as long as libtool
271 has been ported to it.
273 This chapter explains the original design philosophy of libtool. Feel
274 free to skip to the next chapter, unless you are interested in history,
275 or want to write code to extend libtool in a consistent way.
278 * Motivation:: Why does GNU need a libtool?
279 * Issues:: The problems that need to be addressed.
280 * Other implementations:: How other people have solved these issues.
281 * Postmortem:: Learning from past difficulties.
285 @section Motivation for writing libtool
287 @cindex motivation for writing libtool
288 @cindex design philosophy
289 Since early 1995, several different GNU developers have recognized the
290 importance of having shared library support for their packages. The
291 primary motivation for such a change is to encourage modularity and
292 reuse of code (both conceptually and physically) in GNU programs.
294 Such a demand means that the way libraries are built in GNU packages
295 needs to be general, to allow for any library type the package installer
296 might want. The problem is compounded by the absence of a standard
297 procedure for creating shared libraries on different platforms.
299 The following sections outline the major issues facing shared library
300 support in GNU, and how shared library support could be standardized
303 @cindex specifications for libtool
304 @cindex libtool specifications
305 The following specifications were used in developing and evaluating this
310 The system must be as elegant as possible.
313 The system must be fully integrated with the GNU Autoconf and Automake
314 utilities, so that it will be easy for GNU maintainers to use. However,
315 the system must not require these tools, so that it can be used by
319 Portability to other (non-GNU) architectures and tools is desirable.
323 @section Implementation issues
325 @cindex tricky design issues
326 @cindex design issues
327 The following issues need to be addressed in any reusable shared library
328 system, specifically libtool:
332 The package installer should be able to control what sort of libraries
336 It can be tricky to run dynamically linked programs whose libraries have
337 not yet been installed. @code{LD_LIBRARY_PATH} must be set properly (if
338 it is supported), or programs fail to run.
341 The system must operate consistently even on hosts that don't support
345 The commands required to build shared libraries may differ wildly from
346 host to host. These need to be determined at configure time in
350 It is not always obvious with what prefix or suffix a shared library
351 should be installed. This makes it difficult for @file{Makefile} rules,
352 since they generally assume that file names are the same from host to
356 The system needs a simple library version number abstraction, so that
357 shared libraries can be upgraded in place. The programmer should be
358 informed how to design the interfaces to the library to maximize binary
362 The install @file{Makefile} target should warn the package installer to set
363 the proper environment variables (@code{LD_LIBRARY_PATH} or equivalent),
364 or run @command{ldconfig}.
367 @node Other implementations
368 @section Other implementations
370 Even before libtool was developed, many free software packages built and
371 installed their own shared libraries. At first, these packages were
372 examined to avoid reinventing existing features.
374 Now it is clear that none of these packages have documented the details
375 of shared library systems that libtool requires. So, other packages
376 have been more or less abandoned as influences.
379 @section A postmortem analysis of other implementations
381 @cindex other implementations, flaws in
382 @cindex reusability of library systems
383 In all fairness, each of the implementations that were examined do the
384 job that they were intended to do, for a number of different host
385 systems. However, none of these solutions seem to function well as a
386 generalized, reusable component.
388 @cindex complexity of library systems
389 Most were too complex to use (much less modify) without understanding
390 exactly what the implementation does, and they were generally not
393 The main difficulty is that different vendors have different views of
394 what libraries are, and none of the packages that were examined seemed
395 to be confident enough to settle on a single paradigm that just
398 Ideally, libtool would be a standard that would be implemented as series
399 of extensions and modifications to existing library systems to make them
400 work consistently. However, it is not an easy task to convince
401 operating system developers to mend their evil ways, and people want to
402 build shared libraries right now, even on buggy, broken, confused
405 For this reason, libtool was designed as an independent shell script.
406 It isolates the problems and inconsistencies in library building that
407 plague @file{Makefile} writers by wrapping the compiler suite on
408 different platforms with a consistent, powerful interface.
410 With luck, libtool will be useful to and used by the GNU community, and
411 that the lessons that were learned in writing it will be taken up by
412 designers of future library systems.
414 @node Libtool paradigm
415 @chapter The libtool paradigm
417 At first, libtool was designed to support an arbitrary number of library
418 object types. After libtool was ported to more platforms, a new
419 paradigm gradually developed for describing the relationship between
420 libraries and programs.
422 @cindex definition of libraries
423 @cindex libraries, definition of
424 In summary, ``libraries are programs with multiple entry points, and
425 more formally defined interfaces.''
427 Version 0.7 of libtool was a complete redesign and rewrite of libtool to
428 reflect this new paradigm. So far, it has proved to be successful:
429 libtool is simpler and more useful than before.
431 The best way to introduce the libtool paradigm is to contrast it with
432 the paradigm of existing library systems, with examples from each. It
433 is a new way of thinking, so it may take a little time to absorb, but
434 when you understand it, the world becomes simpler.
437 @chapter Using libtool
439 @cindex examples of using libtool
440 @cindex libtool examples
441 It makes little sense to talk about using libtool in your own packages
442 until you have seen how it makes your life simpler. The examples in
443 this chapter introduce the main features of libtool by comparing the
444 standard library building procedure to libtool's operation on two
449 An Ultrix 4.2 platform with only static libraries.
452 A NetBSD/i386 1.2 platform with shared libraries.
455 You can follow these examples on your own platform, using the
456 preconfigured libtool script that was installed with libtool
457 (@pxref{Configuring}).
459 Source files for the following examples are taken from the @file{demo}
460 subdirectory of the libtool distribution. Assume that we are building a
461 library, @file{libhello}, out of the files @file{foo.c} and
464 Note that the @file{foo.c} source file uses the @code{cos} math library
465 function, which is usually found in the standalone math library, and not
466 the C library (@pxref{Trig Functions, , Trigonometric Functions, libc,
467 The GNU C Library Reference Manual}). So, we need to add @option{-lm} to
468 the end of the link line whenever we link @file{foo.lo} into an
469 executable or a library (@pxref{Inter-library dependencies}).
471 The same rule applies whenever you use functions that don't appear in
472 the standard C library@dots{} you need to add the appropriate
473 @option{-l@var{name}} flag to the end of the link line when you link
474 against those objects.
476 After we have built that library, we want to create a program by linking
477 @file{main.o} against @file{libhello}.
480 * Creating object files:: Compiling object files for libraries.
481 * Linking libraries:: Creating libraries from object files.
482 * Linking executables:: Linking object files against libtool libraries.
483 * Debugging executables:: Running GDB on libtool-generated programs.
484 * Installing libraries:: Making libraries available to users.
485 * Installing executables:: Making programs available to users.
486 * Static libraries:: When shared libraries are not wanted.
489 @node Creating object files
490 @section Creating object files
492 @cindex compiling object files
493 @cindex object files, compiling
494 To create an object file from a source file, the compiler is invoked
495 with the @option{-c} flag (and any other desired flags):
498 burger$ @kbd{gcc -g -O -c main.c}
502 The above compiler command produces an object file, usually named
503 @file{main.o}, from the source file @file{main.c}.
505 For most library systems, creating object files that become part of a
506 static library is as simple as creating object files that are linked to
510 burger$ @kbd{gcc -g -O -c foo.c}
511 burger$ @kbd{gcc -g -O -c hello.c}
515 @cindex position-independent code
516 @cindex PIC (position-independent code)
517 Shared libraries, however, may only be built from
518 @dfn{position-independent code} (PIC). So, special flags must be passed
519 to the compiler to tell it to generate PIC rather than the standard
520 position-dependent code.
522 @cindex library object file
523 @cindex @file{.lo} files
524 @cindex object files, library
525 Since this is a library implementation detail, libtool hides the
526 complexity of PIC compiler flags and uses separate library object files
527 (the PIC one lives in the @file{@value{objdir}} subdirectory and the
528 static one lives in the current directory). On systems without shared
529 libraries, the PIC library object files are not created, whereas on
530 systems where all code is PIC, such as AIX, the static ones are not
533 To create library object files for @file{foo.c} and @file{hello.c},
534 simply invoke libtool with the standard compilation command as
535 arguments (@pxref{Compile mode}):
538 a23$ @kbd{libtool --mode=compile gcc -g -O -c foo.c}
539 gcc -g -O -c foo.c -o foo.o
540 a23$ @kbd{libtool --mode=compile gcc -g -O -c hello.c}
541 gcc -g -O -c hello.c -o hello.o
545 Note that libtool silently creates an additional control file on each
546 @samp{compile} invocation. The @file{.lo} file is the libtool object,
547 which Libtool uses to determine what object file may be built into a
548 shared library. On @samp{a23}, only static libraries are supported so
549 the library objects look like this:
552 # foo.lo - a libtool object file
553 # Generated by ltmain.sh (GNU libtool) @value{VERSION}
555 # Please DO NOT delete this file!
556 # It is necessary for linking the library.
558 # Name of the PIC object.
561 # Name of the non-PIC object.
562 non_pic_object='foo.o'
565 On shared library systems, libtool automatically generates an
566 additional PIC object by inserting the appropriate PIC generation
567 flags into the compilation command:
570 burger$ @kbd{libtool --mode=compile gcc -g -O -c foo.c}
572 gcc -g -O -c foo.c -fPIC -DPIC -o @value{objdir}/foo.o
573 gcc -g -O -c foo.c -o foo.o >/dev/null 2>&1
577 Note that Libtool automatically created @file{@value{objdir}} directory
578 upon its first execution, where PIC library object files will be stored.
580 Since @samp{burger} supports shared libraries, and requires PIC
581 objects to build them, Libtool has compiled a PIC object this time,
582 and made a note of it in the libtool object:
585 # foo.lo - a libtool object file
586 # Generated by ltmain.sh (GNU libtool) @value{VERSION}
588 # Please DO NOT delete this file!
589 # It is necessary for linking the library.
591 # Name of the PIC object.
592 pic_object='@value{objdir}/foo.o'
594 # Name of the non-PIC object.
595 non_pic_object='foo.o'
598 @cindex @option{-no-suppress}, libtool compile mode option
599 Notice that the second run of GCC has its output discarded. This is
600 done so that compiler warnings aren't annoyingly duplicated. If you
601 need to see both sets of warnings (you might have conditional code
602 inside @samp{#ifdef PIC} for example), you can turn off suppression with
603 the @option{-no-suppress} option to libtool's compile mode:
606 burger$ @kbd{libtool --mode=compile gcc -no-suppress -g -O -c hello.c}
607 gcc -g -O -c hello.c -fPIC -DPIC -o @value{objdir}/hello.o
608 gcc -g -O -c hello.c -o hello.o
613 @node Linking libraries
614 @section Linking libraries
617 Without libtool, the programmer would invoke the @command{ar} command to
618 create a static library:
621 burger$ @kbd{ar cru libhello.a hello.o foo.o}
626 But of course, that would be too simple, so many systems require that
627 you run the @code{ranlib} command on the resulting library (to give it
628 better karma, or something):
631 burger$ @kbd{ranlib libhello.a}
635 It seems more natural to use the C compiler for this task, given
636 libtool's ``libraries are programs'' approach. So, on platforms without
637 shared libraries, libtool simply acts as a wrapper for the system
638 @command{ar} (and possibly @code{ranlib}) commands.
640 @cindex libtool libraries
641 @cindex @file{.la} files
642 Again, the libtool control file name (@file{.la} suffix) differs from
643 the standard library name (@file{.a} suffix). The arguments to
644 libtool are the same ones you would use to produce an executable named
645 @file{libhello.la} with your compiler (@pxref{Link mode}):
648 a23$ @kbd{libtool --mode=link gcc -g -O -o libhello.la foo.o hello.o}
649 *** Warning: Linking the shared library libhello.la against the
650 *** non-libtool objects foo.o hello.o is not portable!
651 ar cru .libs/libhello.a
652 ranlib .libs/libhello.a
654 (cd .libs && rm -f libhello.la && ln -s ../libhello.la libhello.la)
658 Aha! Libtool caught a common error@dots{} trying to build a library
659 from standard objects instead of special @file{.lo} object files. This
660 doesn't matter so much for static libraries, but on shared library
661 systems, it is of great importance. (Note that you may replace
662 @file{libhello.la} with @file{libhello.a} in which case libtool won't
663 issue the warning any more. But although this method works, this is
664 not intended to be used because it makes you lose the benefits of
667 So, let's try again, this time with the library object files. Remember
668 also that we need to add @option{-lm} to the link command line because
669 @file{foo.c} uses the @code{cos} math library function (@pxref{Using
672 Another complication in building shared libraries is that we need to
673 specify the path to the directory in which they (eventually) will be
674 installed (in this case, @file{/usr/local/lib})@footnote{If you don't
675 specify an @code{rpath}, then libtool builds a libtool convenience
676 archive, not a shared library (@pxref{Static libraries}).}:
679 a23$ @kbd{libtool --mode=link gcc -g -O -o libhello.la foo.lo hello.lo \
680 -rpath /usr/local/lib -lm}
681 ar cru @value{objdir}/libhello.a foo.o hello.o
682 ranlib @value{objdir}/libhello.a
684 (cd @value{objdir} && rm -f libhello.la && ln -s ../libhello.la libhello.la)
688 Now, let's try the same trick on the shared library platform:
691 burger$ @kbd{libtool --mode=link gcc -g -O -o libhello.la foo.lo hello.lo \
692 -rpath /usr/local/lib -lm}
693 rm -fr @value{objdir}/libhello.a @value{objdir}/libhello.la
694 ld -Bshareable -o @value{objdir}/libhello.so.0.0 @value{objdir}/foo.o @value{objdir}/hello.o -lm
695 ar cru @value{objdir}/libhello.a foo.o hello.o
696 ranlib @value{objdir}/libhello.a
698 (cd @value{objdir} && rm -f libhello.la && ln -s ../libhello.la libhello.la)
702 Now that's significantly cooler@dots{} Libtool just ran an obscure
703 @command{ld} command to create a shared library, as well as the static
706 @cindex @file{@value{objdir}} subdirectory
707 Note how libtool creates extra files in the @file{@value{objdir}}
708 subdirectory, rather than the current directory. This feature is to
709 make it easier to clean up the build directory, and to help ensure that
710 other programs fail horribly if you accidentally forget to use libtool
713 Again, you may want to have a look at the @file{.la} file in order
714 to see what Libtool stores in it. In particular, you will see that
715 Libtool uses this file to remember the destination directory for the
716 library (the argument to @option{-rpath}) as well as the dependency
717 on the math library (@samp{-lm}).
719 @node Linking executables
720 @section Linking executables
722 @cindex linking against installed libraries
723 If you choose at this point to @dfn{install} the library (put it in a
724 permanent location) before linking executables against it, then you
725 don't need to use libtool to do the linking. Simply use the appropriate
726 @option{-L} and @option{-l} flags to specify the library's location.
728 @cindex buggy system linkers
729 Some system linkers insist on encoding the full directory name of each
730 shared library in the resulting executable. Libtool has to work around
731 this misfeature by special magic to ensure that only permanent directory
732 names are put into installed executables.
734 @cindex security problems with buggy linkers
735 @cindex bugs, subtle ones caused by buggy linkers
736 The importance of this bug must not be overlooked: it won't cause
737 programs to crash in obvious ways. It creates a security hole,
738 and possibly even worse, if you are modifying the library source code
739 after you have installed the package, you will change the behaviour of
740 the installed programs!
742 So, if you want to link programs against the library before you install
743 it, you must use libtool to do the linking.
745 @cindex linking against uninstalled libraries
746 Here's the old way of linking against an uninstalled library:
749 burger$ @kbd{gcc -g -O -o hell.old main.o libhello.a -lm}
753 Libtool's way is almost the same@footnote{However, you should avoid using
754 @option{-L} or @option{-l} flags to link against an uninstalled libtool
755 library. Just specify the relative path to the @file{.la} file, such as
756 @file{../intl/libintl.la}. This is a design decision to eliminate any
757 ambiguity when linking against uninstalled shared libraries.}
761 a23$ @kbd{libtool --mode=link gcc -g -O -o hell main.o libhello.la}
762 gcc -g -O -o hell main.o ./@value{objdir}/libhello.a -lm
766 That looks too simple to be true. All libtool did was transform
767 @file{libhello.la} to @file{./@value{objdir}/libhello.a}, but remember
768 that @samp{a23} has no shared libraries. Notice that Libtool also
769 remembered that @file{libhello.la} depends on @option{-lm}, so even
770 though we didn't specify @option{-lm} on the libtool command
773 And why should we? @file{main.o} doesn't directly depend on @option{-lm}
776 } Libtool has added it to the @command{gcc} link line for us.
778 On @samp{burger} Libtool links against the uninstalled shared library:
781 burger$ @kbd{libtool --mode=link gcc -g -O -o hell main.o libhello.la}
782 gcc -g -O -o @value{objdir}/hell main.o -L./@value{objdir} -R/usr/local/lib -lhello -lm
787 @cindex linking with installed libtool libraries
788 Now assume @file{libhello.la} had already been installed, and you want
789 to link a new program with it. You could figure out where it lives by
793 burger$ @kbd{gcc -g -O -o test test.o -L/usr/local/lib -lhello -lm}
796 However, unless @file{/usr/local/lib} is in the standard library search
797 path, you won't be able to run @code{test}. However, if you use libtool
798 to link the already-installed libtool library, it will do The Right
802 burger$ @kbd{libtool --mode=link gcc -g -O -o test test.o \
803 /usr/local/lib/libhello.la}
804 gcc -g -O -o @value{objdir}/test test.o -Wl,--rpath \
805 -Wl,/usr/local/lib /usr/local/lib/libhello.a -lm
810 Note that libtool added the necessary run-time path flag, as well as
811 @option{-lm}, the library libhello.la depended upon. Nice, huh?
813 @cindex wrapper scripts for programs
814 @cindex program wrapper scripts
815 Notice that the executable, @code{hell}, was actually created in the
816 @file{@value{objdir}} subdirectory. Then, a wrapper script (or, on
817 certain platforms, a wrapper executable @pxref{Wrapper executables}) was
818 created in the current directory.
820 Since libtool created a wrapper script, you should use libtool to
821 install it and debug it too. However, since the program does not depend
822 on any uninstalled libtool library, it is probably usable even without
825 On NetBSD 1.2, libtool encodes the installation directory of
826 @file{libhello}, by using the @samp{-R/usr/local/lib} compiler flag.
827 Then, the wrapper script guarantees that the executable finds the
828 correct shared library (the one in @file{./@value{objdir}}) until it is
831 Let's compare the two different programs:
834 burger$ @kbd{time ./hell.old}
836 ** This is not GNU Hello. There is no built-in mail reader. **
837 0.21 real 0.02 user 0.08 sys
838 burger$ @kbd{time ./hell}
840 ** This is not GNU Hello. There is no built-in mail reader. **
841 0.63 real 0.09 user 0.59 sys
845 The wrapper script takes significantly longer to execute, but at least
846 the results are correct, even though the shared library hasn't been
849 So, what about all the space savings that shared libraries are supposed
853 burger$ @kbd{ls -l hell.old libhello.a}
854 -rwxr-xr-x 1 gord gord 15481 Nov 14 12:11 hell.old
855 -rw-r--r-- 1 gord gord 4274 Nov 13 18:02 libhello.a
856 burger$ @kbd{ls -l @value{objdir}/hell @value{objdir}/libhello.*}
857 -rwxr-xr-x 1 gord gord 11647 Nov 14 12:10 @value{objdir}/hell
858 -rw-r--r-- 1 gord gord 4274 Nov 13 18:44 @value{objdir}/libhello.a
859 -rwxr-xr-x 1 gord gord 12205 Nov 13 18:44 @value{objdir}/libhello.so.0.0
863 Well, that sucks. Maybe I should just scrap this project and take up
866 Actually, it just proves an important point: shared libraries incur
867 overhead because of their (relative) complexity. In this situation, the
868 price of being dynamic is eight kilobytes, and the payoff is about four
869 kilobytes. So, having a shared @file{libhello} won't be an advantage
870 until we link it against at least a few more programs.
873 * Wrapper executables:: Wrapper executables for some platforms.
876 @node Wrapper executables
877 @subsection Wrapper executables for uninstalled programs
878 @cindex wrapper executables for uninstalled programs
879 @cindex program wrapper executables
881 Some platforms, notably those hosted on Windows such as Cygwin
882 and MinGW, use a wrapper executable rather than a wrapper script
883 to ensure proper operation of uninstalled programs linked by libtool
884 against uninstalled shared libraries. The wrapper executable thus
885 performs the same function as the wrapper script used on other
886 platforms, but allows to satisfy the @command{make} rules for the
887 program, whose name ends in @code{$(EXEEXT)}. The actual program
888 executable is created below @value{objdir}, and its name will end
889 in @code{$(EXEEXT)} and may or may not contain an @code{lt-} prefix.
890 This wrapper executable sets various environment values so that the
891 program executable may locate its (uninstalled) shared libraries,
892 and then launches the program executable.
894 The wrapper executable provides a debug mode, enabled by passing the
895 command-line option @code{--lt-debug} (see below). When executing in
896 debug mode, diagnostic information will be printed to @code{stderr}
897 before the program executable is launched.
899 Finally, the wrapper executable supports a number of command line
900 options that may be useful when debugging the operation of the wrapper
901 system. All of these options begin with @code{--lt-}, and if present
902 they and their arguments will be removed from the argument list passed
903 on to the program executable. Therefore, the program executable may not
904 employ command line options that begin with @code{--lt-}. (In fact, the
905 wrapper executable will detect any command line options that begin with
906 @code{--lt-} and abort with an error message if the option is not
907 recognized). If this presents a problem, please contact the Libtool
908 team at @value{BUGADDR}.
910 These command line options include:
913 @item --lt-dump-script
914 Causes the wrapper to print a copy of the wrapper @emph{script}
915 to @code{stdout}, and exit.
918 Causes the wrapper to print diagnostic information to @code{stdout},
919 before launching the program executable.
923 For consistency, both the wrapper @emph{script} and the wrapper
924 @emph{executable} support these options.
926 @node Debugging executables
927 @section Debugging executables
929 If @file{hell} was a complicated program, you would certainly want to
930 test and debug it before installing it on your system. In the above
931 section, you saw how the libtool wrapper script makes it possible to run
932 the program directly, but unfortunately, this mechanism interferes with
936 burger$ @kbd{gdb hell}
937 GDB is free software and you are welcome to distribute copies of it
938 under certain conditions; type "show copying" to see the conditions.
939 There is no warranty for GDB; type "show warranty" for details.
940 GDB 4.16 (i386-unknown-netbsd), (C) 1996 Free Software Foundation, Inc.
942 "hell": not in executable format: File format not recognized
948 Sad. It doesn't work because GDB doesn't know where the executable
949 lives. So, let's try again, by invoking GDB directly on the executable:
952 burger$ @kbd{gdb @value{objdir}/hell}
953 GNU gdb 5.3 (i386-unknown-netbsd)
954 Copyright 2002 Free Software Foundation, Inc.
955 GDB is free software, covered by the GNU General Public License,
956 and you are welcome to change it and/or distribute copies of it
957 under certain conditions. Type "show copying" to see the conditions.
958 There is no warranty for GDB. Type "show warranty" for details.
959 (gdb) @kbd{break main}
960 Breakpoint 1 at 0x8048547: file main.c, line 29.
962 Starting program: /home/src/libtool/demo/.libs/hell
963 /home/src/libtool/demo/.libs/hell: can't load library 'libhello.so.0'
965 Program exited with code 020.
970 Argh. Now GDB complains because it cannot find the shared library that
971 @file{hell} is linked against. So, we must use libtool in order to
972 properly set the library path and run the debugger. Fortunately, we can
973 forget all about the @file{@value{objdir}} directory, and just run it on
974 the executable wrapper (@pxref{Execute mode}):
977 burger$ @kbd{libtool --mode=execute gdb hell}
978 GNU gdb 5.3 (i386-unknown-netbsd)
979 Copyright 2002 Free Software Foundation, Inc.
980 GDB is free software, covered by the GNU General Public License,
981 and you are welcome to change it and/or distribute copies of it
982 under certain conditions. Type "show copying" to see the conditions.
983 There is no warranty for GDB. Type "show warranty" for details.
984 (gdb) @kbd{break main}
985 Breakpoint 1 at 0x8048547: file main.c, line 29.
987 Starting program: /home/src/libtool/demo/.libs/hell
989 Breakpoint 1, main (argc=1, argv=0xbffffc40) at main.c:29
990 29 printf ("Welcome to GNU Hell!\n");
992 The program is running. Quit anyway (and kill it)? (y or n) @kbd{y}
996 @node Installing libraries
997 @section Installing libraries
1000 Installing libraries on a non-libtool system is quite
1001 straightforward@dots{} just copy them into place:@footnote{Don't
1002 strip static libraries though, or they will be unusable.}
1007 Password: @kbd{********}
1008 burger# @kbd{cp libhello.a /usr/local/lib/libhello.a}
1012 Oops, don't forget the @command{ranlib} command:
1015 burger# @kbd{ranlib /usr/local/lib/libhello.a}
1020 Libtool installation is quite simple, as well. Just use the
1021 @command{install} or @command{cp} command that you normally would
1022 (@pxref{Install mode}):
1025 a23# @kbd{libtool --mode=install cp libhello.la /usr/local/lib/libhello.la}
1026 cp libhello.la /usr/local/lib/libhello.la
1027 cp @value{objdir}/libhello.a /usr/local/lib/libhello.a
1028 ranlib /usr/local/lib/libhello.a
1032 Note that the libtool library @file{libhello.la} is also installed, to
1033 help libtool with uninstallation (@pxref{Uninstall mode}) and linking
1034 (@pxref{Linking executables}) and to help programs with dlopening
1035 (@pxref{Dlopened modules}).
1037 Here is the shared library example:
1040 burger# @kbd{libtool --mode=install install -c libhello.la \
1041 /usr/local/lib/libhello.la}
1042 install -c @value{objdir}/libhello.so.0.0 /usr/local/lib/libhello.so.0.0
1043 install -c libhello.la /usr/local/lib/libhello.la
1044 install -c @value{objdir}/libhello.a /usr/local/lib/libhello.a
1045 ranlib /usr/local/lib/libhello.a
1049 @cindex stripping libraries
1050 @cindex libraries, stripping
1051 It is safe to specify the @option{-s} (strip symbols) flag if you use a
1052 BSD-compatible install program when installing libraries.
1053 Libtool will either ignore the @option{-s} flag, or will run a program
1054 that will strip only debugging and compiler symbols from the library.
1056 Once the libraries have been put in place, there may be some additional
1057 configuration that you need to do before using them. First, you must
1058 make sure that where the library is installed actually agrees with the
1059 @option{-rpath} flag you used to build it.
1061 @cindex postinstallation
1062 @cindex installation, finishing
1063 @cindex libraries, finishing installation
1064 Then, running @samp{libtool -n finish @var{libdir}} can give you
1065 further hints on what to do (@pxref{Finish mode}):
1068 burger# @kbd{libtool -n finish /usr/local/lib}
1069 PATH="$PATH:/sbin" ldconfig -m /usr/local/lib
1070 -----------------------------------------------------------------
1071 Libraries have been installed in:
1074 To link against installed libraries in a given directory, LIBDIR,
1075 you must use the `-LLIBDIR' flag during linking.
1077 You will also need to do one of the following:
1078 - add LIBDIR to the `LD_LIBRARY_PATH' environment variable
1080 - add LIBDIR to the `LD_RUN_PATH' environment variable
1082 - use the `-RLIBDIR' linker flag
1084 See any operating system documentation about shared libraries for
1085 more information, such as the ld and ld.so manual pages.
1086 -----------------------------------------------------------------
1090 After you have completed these steps, you can go on to begin using the
1091 installed libraries. You may also install any executables that depend
1092 on libraries you created.
1094 @node Installing executables
1095 @section Installing executables
1097 If you used libtool to link any executables against uninstalled libtool
1098 libraries (@pxref{Linking executables}), you need to use libtool to
1099 install the executables after the libraries have been installed
1100 (@pxref{Installing libraries}).
1102 So, for our Ultrix example, we would run:
1105 a23# libtool --mode=install -c hell /usr/local/bin/hell
1106 install -c hell /usr/local/bin/hell
1110 On shared library systems that require wrapper scripts, libtool just
1111 ignores the wrapper script and installs the correct binary:
1114 burger# libtool --mode=install -c hell /usr/local/bin/hell
1115 install -c @value{objdir}/hell /usr/local/bin/hell
1120 @node Static libraries
1121 @section Linking static libraries
1123 @cindex static linking
1124 @cindex convenience libraries
1125 Why return to @command{ar} and @command{ranlib} silliness when you've had a
1126 taste of libtool? Well, sometimes it is desirable to create a static
1127 archive that can never be shared. The most frequent case is when you
1128 have a set of object files that you use to build several different
1129 libraries. You can create a ``convenience library'' out of those
1130 objects, and link against that with the other libraries, instead of
1131 listing all the object files every time.
1133 If you just want to link this convenience library into programs, then
1134 you could just ignore libtool entirely, and use the old @command{ar} and
1135 @command{ranlib} commands (or the corresponding GNU Automake
1136 @samp{_LIBRARIES} rules). You can even install a convenience library
1137 using GNU Libtool, though you probably don't want to and hence GNU
1138 Automake doesn't allow you to do so.
1141 burger$ @kbd{libtool --mode=install ./install-sh -c libhello.a \
1142 /local/lib/libhello.a}
1143 ./install-sh -c libhello.a /local/lib/libhello.a
1144 ranlib /local/lib/libhello.a
1148 Using libtool for static library installation protects your library from
1149 being accidentally stripped (if the installer used the @option{-s} flag),
1150 as well as automatically running the correct @command{ranlib} command.
1152 But libtool libraries are more than just collections of object files:
1153 they can also carry library dependency information, which old archives
1154 do not. If you want to create a libtool static convenience library, you
1155 can omit the @option{-rpath} flag and use @option{-static} to indicate that
1156 you're only interested in a static library. When you link a program
1157 with such a library, libtool will actually link all object files and
1158 dependency libraries into the program.
1160 If you omit both @option{-rpath} and @option{-static}, libtool will create a
1161 convenience library that can be used to create other libtool
1162 libraries, even shared ones. Just like in the static case, the library
1163 behaves as an alias to a set of object files and dependency libraries,
1164 but in this case the object files are suitable for inclusion in shared
1165 libraries. But be careful not to link a single convenience library,
1166 directly or indirectly, into a single program or library, otherwise you
1167 may get errors about symbol redefinitions.
1169 The key is remembering that a convenience library contains PIC
1170 objects, and can be linked where a list of PIC objects makes sense;
1171 i.e.@: into a shared library. A static convenience library contains
1172 non-PIC objects, so can be linked into an old static library, or
1175 When GNU Automake is used, you should use @code{noinst_LTLIBRARIES}
1176 instead of @code{lib_LTLIBRARIES} for convenience libraries, so that
1177 the @option{-rpath} option is not passed when they are linked.
1179 As a rule of thumb, link a libtool convenience library into at most one
1180 libtool library, and never into a program, and link libtool static
1181 convenience libraries only into programs, and only if you need to carry
1182 library dependency information to the user of the static convenience
1185 @cindex standalone binaries
1186 Another common situation where static linking is desirable is in
1187 creating a standalone binary. Use libtool to do the linking and add the
1188 @option{-all-static} flag.
1190 @node Invoking libtool
1191 @chapter Invoking @command{libtool}
1193 @cindex libtool command options
1194 @cindex options, libtool command
1195 @cindex command options, libtool
1197 The @command{libtool} program has the following synopsis:
1200 libtool [@var{option}]@dots{} [@var{mode-arg}]@dots{}
1204 and accepts the following options:
1208 Display libtool configuration variables and exit.
1211 Dump a trace of shell script execution to standard output. This
1212 produces a lot of output, so you may wish to pipe it to @command{less} (or
1213 @command{more}) or redirect to a file.
1217 Don't create, modify, or delete any files, just show what commands would
1218 be executed by libtool.
1221 Display basic configuration options. This provides a way for packages
1222 to determine whether shared or static libraries will be built.
1225 Same as @option{--mode=finish}.
1228 Display short help message.
1231 Display a help message and exit. If @option{--mode=@var{mode}} is
1232 specified, then detailed help for @var{mode} is displayed.
1235 Display help for the general options as well as detailed help for each
1236 operation mode, and exit.
1238 @item --mode=@var{mode}
1239 Use @var{mode} as the operation mode. When using libtool from the
1240 command line, you can give just @var{mode} (or a unique abbreviation
1241 of it) as the first argument as a shorthand for the full
1242 @option{--mode=@var{mode}}. For example, the following are equivalent:
1245 $ @kbd{libtool --mode=execute --dry-run gdb prog.exe}
1246 $ @kbd{libtool execute --dry-run gdb prog.exe}
1247 $ @kbd{libtool exe --dry-run gdb prog.exe}
1248 $ @kbd{libtool e --dry-run gdb prog.exe}
1252 @var{mode} must be set to one of the following:
1256 Compile a source file into a libtool object.
1259 Automatically set the library path so that another program can use
1260 uninstalled libtool-generated programs or libraries.
1263 Create a library or an executable.
1266 Install libraries or executables.
1269 Complete the installation of libtool libraries on the system.
1272 Delete installed libraries or executables.
1275 Delete uninstalled libraries or executables.
1278 @item --tag=@var{tag}
1279 Use configuration variables from tag @var{tag} (@pxref{Tags}).
1281 @item --preserve-dup-deps
1282 Do not remove duplicate dependencies in libraries. When building packages
1283 with static libraries, the libraries may depend circularly on each other
1284 (shared libs can too, but for those it doesn't matter), so there are
1285 situations, where -la -lb -la is required, and the second -la may not be
1286 stripped or the link will fail. In cases where these duplications are
1287 required, this option will preserve them, only stripping the libraries
1288 that libtool knows it can safely.
1292 Do not print out any progress or informational messages.
1296 Print out progress and informational messages (enabled by default),
1297 as well as additional messages not ordinary seen by default.
1301 Print out the progress and informational messages that are seen
1302 by default. This option has no effect on whether the additional
1303 messages seen in @option{--verbose} mode are shown.
1306 Do not print out any additional informational messages beyond
1307 those ordinarily seen by default. This option has no effect
1308 on whether the ordinary progress and informational messages
1309 enabled by @option{--no-quiet} are shown.
1311 Thus, there are now three different message levels (not counting
1312 @option{--debug}), depending on whether the normal messages and/or
1313 the additional verbose messages are displayed. Note that there is
1314 no mechanism to diplay verbose messages, without also displaying
1319 Normal messages are displayed, verbose messages are not displayed.
1320 In addition to being the default mode, it can be forcibly achieved
1321 by using both option @option{--no-verbose} and either option
1322 @option{--no-silent} or option @option{--no-quiet}.
1325 Neither normal messages nor verbose messages are displayed. This
1326 mode can be achieved using either option @option{--silent} or
1327 option @option{--quiet}.
1330 Both normal messages and verbose messages are displayed. This mode
1331 can be achieved using either option @option{-v} or option
1336 Print libtool version information and exit.
1339 The current @command{libtool} implementation is done with a shell script
1340 that needs to be invoked by the shell which @command{configure} chose for
1341 configuring @command{libtool} (@pxref{config.status Invocation, , The
1342 Autoconf Manual, autoconf, The Autoconf Manual}). This shell is set in
1343 the she-bang (@samp{#!}) line of the @command{libtool} script. Using a
1344 different shell may cause undefined behavior.
1346 The @var{mode-args} are a variable number of arguments, depending on the
1347 selected operation mode. In general, each @var{mode-arg} is interpreted
1348 by programs libtool invokes, rather than libtool itself.
1351 * Compile mode:: Creating library object files.
1352 * Link mode:: Generating executables and libraries.
1353 * Execute mode:: Debugging libtool-generated programs.
1354 * Install mode:: Making libraries and executables public.
1355 * Finish mode:: Completing a library installation.
1356 * Uninstall mode:: Removing installed executables and libraries.
1357 * Clean mode:: Removing uninstalled executables and libraries.
1361 @section Compile mode
1362 @cindex mode, compile
1363 @cindex compile mode
1365 For @dfn{compile} mode, @var{mode-args} is a compiler command to be used
1366 in creating a ``standard'' object file. These arguments should begin with
1367 the name of the C compiler, and contain the @option{-c} compiler flag so
1368 that only an object file is created.
1370 Libtool determines the name of the output file by removing the directory
1371 component from the source file name, then substituting the source code
1372 suffix (e.g.@: @samp{.c} for C source code) with the library object suffix,
1375 If shared libraries are being built, any necessary PIC generation flags
1376 are substituted into the compilation command.
1378 The following components of @var{mode-args} are treated specially:
1382 Note that the @option{-o} option is now fully supported. It is emulated
1383 on the platforms that don't support it (by locking and moving the
1384 objects), so it is really easy to use libtool, just with minor
1385 modifications to your Makefiles. Typing for example
1387 libtool --mode=compile gcc -c foo/x.c -o foo/x.lo
1389 will do what you expect.
1391 Note, however, that, if the compiler does not support @option{-c} and
1392 @option{-o}, it is impossible to compile @file{foo/x.c} without
1393 overwriting an existing @file{./x.o}. Therefore, if you do have a
1394 source file @file{./x.c}, make sure you introduce dependencies in your
1395 @file{Makefile} to make sure @file{./x.o} (or @file{./x.lo}) is
1396 re-created after any sub-directory's @file{x.lo}:
1399 x.o x.lo: foo/x.lo bar/x.lo
1403 This will also ensure that make won't try to use a temporarily corrupted
1404 @file{x.o} to create a program or library. It may cause needless
1405 recompilation on platforms that support @option{-c} and @option{-o}
1406 together, but it's the only way to make it safe for those that don't.
1409 If both PIC and non-PIC objects are being built, libtool will normally
1410 suppress the compiler output for the PIC object compilation to save
1411 showing very similar, if not identical duplicate output for each
1412 object. If the @option{-no-suppress} option is given in compile mode,
1413 libtool will show the compiler output for both objects.
1416 Libtool will try to build only PIC objects.
1418 @item -prefer-non-pic
1419 Libtool will try to build only non-PIC objects.
1422 Even if Libtool was configured with @option{--enable-static}, the object
1423 file Libtool builds will not be suitable for static linking. Libtool
1424 will signal an error if it was configured with @option{--disable-shared},
1425 or if the host does not support shared libraries.
1428 Even if libtool was configured with @option{--disable-static}, the
1429 object file Libtool builds @strong{will} be suitable for static
1432 @item -Wc,@var{flag}
1433 @itemx -Xcompiler @var{flag}
1434 Pass a flag directly to the compiler. With @code{-Wc,}, multiple flags
1435 may be separated by commas, whereas @code{-Xcompiler } passes through
1444 @dfn{Link} mode links together object files (including library
1445 objects) to form another library or to create an executable program.
1447 @var{mode-args} consist of a command using the C compiler to create an
1448 output file (with the @option{-o} flag) from several object files.
1450 The following components of @var{mode-args} are treated specially:
1453 @cindex undefined symbols, allowing
1454 @cindex unresolved symbols, allowing
1456 If @var{output-file} is a program, then do not link it against any
1457 shared libraries at all. If @var{output-file} is a library, then only
1458 create a static library. In general, this flag cannot be used together
1459 with @samp{disable-static} (@pxref{LT_INIT}).
1461 @item -avoid-version
1462 Tries to avoid versioning (@pxref{Versioning}) for libraries and modules,
1463 i.e.@: no version information is stored and no symbolic links are created.
1464 If the platform requires versioning, this option has no effect.
1467 Pass the absolute name of the directory for installing executable
1468 programs (@pxref{Directory Variables, , Directory Variables, standards,
1469 The GNU Coding Standards}). @command{libtool} may use this value to
1470 install shared libraries there on systems that do not provide for any
1471 library hardcoding and use the directory of a program and the @env{PATH}
1472 variable as library search path. This is typically used for DLLs on
1473 Windows or other systems using the PE (Portable Executable) format.
1474 On other systems, @option{-bindir} is ignored. The default value used
1475 is @file{@var{libdir}/../bin} for libraries installed to
1476 @file{@var{libdir}}. You should not use @option{-bindir} for modules.
1478 @item -dlopen @var{file}
1479 Same as @option{-dlpreopen @var{file}}, if native dlopening is not
1480 supported on the host platform (@pxref{Dlopened modules}) or if
1481 the program is linked with @option{-static},
1482 @option{-static-libtool-libs}, or @option{-all-static}. Otherwise, no
1483 effect. If @var{file} is @code{self} Libtool will make sure that the
1484 program can @code{dlopen} itself, either by enabling
1485 @option{-export-dynamic} or by falling back to @option{-dlpreopen self}.
1487 @item -dlpreopen @var{file}
1488 Link @var{file} into the output program, and add its symbols to the
1489 list of preloaded symbols (@pxref{Dlpreopening}). If @var{file} is
1490 @code{self}, the symbols of the program itself will be added to
1491 preloaded symbol lists. If @var{file} is @code{force} Libtool will
1492 make sure that a preloaded symbol list is always @emph{defined},
1493 regardless of whether it's empty or not.
1495 @item -export-dynamic
1496 Allow symbols from @var{output-file} to be resolved with @code{dlsym}
1497 (@pxref{Dlopened modules}).
1499 @item -export-symbols @var{symfile}
1500 Tells the linker to export only the symbols listed in @var{symfile}.
1501 The symbol file should end in @file{.sym} and must contain the name of one
1502 symbol per line. This option has no effect on some platforms.
1503 By default all symbols are exported.
1505 @item -export-symbols-regex @var{regex}
1506 Same as @option{-export-symbols}, except that only symbols matching
1507 the regular expression @var{regex} are exported.
1508 By default all symbols are exported.
1510 @item -L@var{libdir}
1511 Search @var{libdir} for required libraries that have already been
1515 @var{output-file} requires the installed library @file{lib@var{name}}.
1516 This option is required even when @var{output-file} is not an
1520 Creates a library that can be dlopened (@pxref{Dlopened modules}).
1521 This option doesn't work for programs.
1522 Module names don't need to be prefixed with @samp{lib}.
1523 In order to prevent name clashes, however, @file{lib@var{name}} and @file{@var{name}}
1524 must not be used at the same time in your package.
1526 @item -no-fast-install
1527 Disable fast-install mode for the executable @var{output-file}. Useful
1528 if the program won't be necessarily installed.
1531 Link an executable @var{output-file} that can't be installed and
1532 therefore doesn't need a wrapper script on systems that allow hardcoding
1533 of library paths. Useful if the program is only used in the build tree,
1534 e.g., for testing or generating other files.
1537 Declare that @var{output-file} does not depend on any libraries other
1538 than the ones listed on the command line, i.e., after linking, it will
1539 not have unresolved symbols. Some platforms require all symbols in
1540 shared libraries to be resolved at library creation (@pxref{Inter-library
1541 dependencies}), and using this parameter allows @command{libtool} to
1542 assume that this will not happen.
1544 @item -o @var{output-file}
1545 Create @var{output-file} from the specified objects and libraries.
1547 @item -objectlist @var{file}
1548 Use a list of object files found in @var{file} to specify objects.
1550 @item -precious-files-regex @var{regex}
1551 Prevents removal of files from the temporary output directory whose
1552 names match this regular expression. You might specify @samp{\.bbg?$}
1553 to keep those files created with @code{gcc -ftest-coverage} for example.
1555 @item -release @var{release}
1556 Specify that the library was generated by release @var{release} of your
1557 package, so that users can easily tell which versions are newer than
1558 others. Be warned that no two releases of your package will be binary
1559 compatible if you use this flag. If you want binary compatibility, use
1560 the @option{-version-info} flag instead (@pxref{Versioning}).
1562 @item -rpath @var{libdir}
1563 If @var{output-file} is a library, it will eventually be installed in
1564 @var{libdir}. If @var{output-file} is a program, add @var{libdir} to
1565 the run-time path of the program. On platforms that don't support
1566 hardcoding library paths into executables and only search PATH for
1567 shared libraries, such as when @var{output-file} is a Windows (or
1568 other PE platform) DLL, the @file{.la} control file will be installed in
1569 @var{libdir}, but see @option{-bindir} above for the eventual destination
1570 of the @file{.dll} or other library file itself.
1572 @item -R @var{libdir}
1573 If @var{output-file} is a program, add @var{libdir} to its run-time
1574 path. If @var{output-file} is a library, add @option{-R@var{libdir}} to its
1575 @var{dependency_libs}, so that, whenever the library is linked into a
1576 program, @var{libdir} will be added to its run-time path.
1579 If @var{output-file} is a program, then link it against any
1580 uninstalled shared libtool libraries (this is the default behavior).
1581 If @var{output-file} is a library, then only create a shared library.
1582 In the later case, libtool will signal an error if it was configured
1583 with @option{--disable-shared}, or if the host does not support shared
1586 @item -shrext @var{suffix}
1587 If @var{output-file} is a libtool library, replace the system's standard
1588 file name extension for shared libraries with @var{suffix} (most systems
1589 use @file{.so} here). This option is helpful in certain cases where an
1590 application requires that shared libraries (typically modules) have an
1591 extension other than the default one. Please note you must supply the
1592 full file name extension including any leading dot.
1595 If @var{output-file} is a program, then do not link it against any
1596 uninstalled shared libtool libraries. If @var{output-file} is a
1597 library, then only create a static library.
1599 @item -static-libtool-libs
1600 If @var{output-file} is a program, then do not link it against any
1601 shared libtool libraries. If @var{output-file} is a library, then only
1602 create a static library.
1604 @item -version-info @var{current}[:@var{revision}[:@var{age}]]
1605 If @var{output-file} is a libtool library, use interface version
1606 information @var{current}, @var{revision}, and @var{age} to build it
1607 (@pxref{Versioning}). Do @strong{not} use this flag to specify package
1608 release information, rather see the @option{-release} flag.
1610 @item -version-number @var{major}[:@var{minor}[:@var{revision}]]
1611 If @var{output-file} is a libtool library, compute interface version
1612 information so that the resulting library uses the specified major, minor and
1613 revision numbers. This is designed to permit libtool to be used with
1614 existing projects where identical version numbers are already used across
1615 operating systems. New projects should use the @option{-version-info} flag
1618 @item -weak @var{libname}
1619 if @var{output-file} is a libtool library, declare that it provides a
1620 weak @var{libname} interface. This is a hint to libtool that there is
1621 no need to append @var{libname} to the list of dependency libraries of
1622 @var{output-file}, because linking against @var{output-file} already
1623 supplies the same interface (@pxref{Linking with dlopened modules}).
1625 @item -Wc,@var{flag}
1626 @itemx -Xcompiler @var{flag}
1627 Pass a linker-specific flag directly to the compiler. With @code{-Wc,},
1628 multiple flags may be separated by commas, whereas @code{-Xcompiler }
1629 passes through commas unchanged.
1631 @item -Wl,@var{flag}
1632 @itemx -Xlinker @var{flag}
1633 Pass a linker-specific flag directly to the linker.
1635 @item -XCClinker @var{flag}
1636 Pass a link-specific flag to the compiler driver (@code{CC}) during linking.
1639 If the @var{output-file} ends in @file{.la}, then a libtool library is
1640 created, which must be built only from library objects (@file{.lo} files).
1641 The @option{-rpath} option is required. In the current implementation,
1642 libtool libraries may not depend on other uninstalled libtool libraries
1643 (@pxref{Inter-library dependencies}).
1645 If the @var{output-file} ends in @file{.a}, then a standard library is
1646 created using @code{ar} and possibly @code{ranlib}.
1648 @cindex partial linking
1649 @cindex linking, partial
1650 If @var{output-file} ends in @file{.o} or @file{.lo}, then a reloadable object
1651 file is created from the input files (generally using @samp{ld -r}).
1652 This method is often called @dfn{partial linking}.
1654 Otherwise, an executable program is created.
1657 @section Execute mode
1658 @cindex execute mode
1659 @cindex mode, execute
1661 For @dfn{execute} mode, the library path is automatically set, then a
1662 program is executed.
1664 The first of the @var{mode-args} is treated as a program name, with the
1665 rest as arguments to that program.
1667 The following components of @var{mode-args} are treated specially:
1670 @item -dlopen @var{file}
1671 Add the directory containing @var{file} to the library path.
1674 This mode sets the library path environment variable according to any
1675 @option{-dlopen} flags.
1677 If any of the @var{args} are libtool executable wrappers, then they are
1678 translated into the name of their corresponding uninstalled binary, and
1679 any of their required library directories are added to the library path.
1682 @section Install mode
1683 @cindex install mode
1684 @cindex mode, install
1686 In @dfn{install} mode, libtool interprets most of the elements of
1687 @var{mode-args} as an installation command beginning with
1688 @command{cp}, or a BSD-compatible @command{install} program.
1690 The following components of @var{mode-args} are treated specially:
1693 @item -inst-prefix-dir @var{inst-prefix-dir}
1694 When installing into a temporary staging area, rather than the
1695 final @code{prefix}, this argument is used to reflect the
1696 temporary path, in much the same way @command{automake} uses
1697 @env{DESTDIR}. For instance, if @code{prefix} is @file{/usr/local},
1698 but @var{inst-prefix-dir} is @file{/tmp}, then the object will be
1699 installed under @file{/tmp/usr/local/}. If the installed object
1700 is a libtool library, then the internal fields of that library
1701 will reflect only @code{prefix}, not @var{inst-prefix-dir}:
1704 # Directory that this library needs to be installed in:
1705 libdir='/usr/local/lib'
1711 # Directory that this library needs to be installed in:
1712 libdir='/tmp/usr/local/lib'
1715 @code{inst-prefix} is also used to insure that if the installed
1716 object must be relinked upon installation, that it is relinked
1717 against the libraries in @var{inst-prefix-dir}/@code{prefix},
1720 In truth, this option is not really intended for use when calling
1721 libtool directly; it is automatically used when @code{libtool --mode=install}
1722 calls @code{libtool --mode=relink}. Libtool does this by
1723 analyzing the destination path given in the original
1724 @code{libtool --mode=install} command and comparing it to the
1725 expected installation path established during @code{libtool --mode=link}.
1727 Thus, end-users need change nothing, and @command{automake}-style
1728 @code{make install DESTDIR=/tmp} will Just Work(tm) most of the time.
1729 For systems where fast installation can not be turned on, relinking
1730 may be needed. In this case, a @samp{DESTDIR} install will fail.
1732 Currently it is not generally possible to install into a temporary
1733 staging area that contains needed third-party libraries which are
1734 not yet visible at their final location.
1737 The rest of the @var{mode-args} are interpreted as arguments to the
1738 @command{cp} or @command{install} command.
1740 The command is run, and any necessary unprivileged post-installation
1741 commands are also completed.
1744 @section Finish mode
1746 @cindex mode, finish
1748 @dfn{Finish} mode has two functions. One is to help system administrators
1749 install libtool libraries so that they can be located and linked into
1750 user programs. To invoke this functionality, pass the name of a library
1751 directory as @var{mode-arg}. Running this command may require superuser
1752 privileges, and the @option{--dry-run} option may be useful.
1754 The second is to facilitate transferring libtool libraries to a native
1755 compilation environment after they were built in a cross-compilation
1756 environment. Cross-compilation environments may rely on recent libtool
1757 features, and running libtool in finish mode will make it easier to
1758 work with older versions of libtool. This task is performed whenever
1759 the @var{mode-arg} is a @file{.la} file.
1761 @node Uninstall mode
1762 @section Uninstall mode
1763 @cindex uninstall mode
1764 @cindex mode, uninstall
1766 @dfn{Uninstall} mode deletes installed libraries, executables and objects.
1768 The first @var{mode-arg} is the name of the program to use to delete
1769 files (typically @command{/bin/rm}).
1771 The remaining @var{mode-args} are either flags for the deletion program
1772 (beginning with a @samp{-}), or the names of files to delete.
1779 @dfn{Clean} mode deletes uninstalled libraries, executables, objects
1780 and libtool's temporary files associated with them.
1782 The first @var{mode-arg} is the name of the program to use to delete
1783 files (typically @command{/bin/rm}).
1785 The remaining @var{mode-args} are either flags for the deletion program
1786 (beginning with a @samp{-}), or the names of files to delete.
1788 @node Integrating libtool
1789 @chapter Integrating libtool with your package
1791 This chapter describes how to integrate libtool with your packages so
1792 that your users can install hassle-free shared libraries.
1794 There are several ways in which Libtool may be integrated in your
1795 package, described in the following sections. Typically, the Libtool
1796 macro files as well as @file{ltmain.sh} are copied into your package
1797 using @command{libtoolize} and @command{aclocal} after setting up the
1798 @file{configure.ac} and toplevel @file{Makefile.am}, then
1799 @command{autoconf} adds the needed tests to the @file{configure} script.
1800 These individual steps are often automated with @command{autoreconf}.
1802 Here is a diagram showing how such a typical Libtool configuration works
1803 when preparing a package for distribution, assuming that @file{m4} has
1804 been chosen as location for additional Autoconf macros, and
1805 @file{build-aux} as location for auxiliary build tools (@pxref{Input,,
1806 The Autoconf Manual, autoconf, The Autoconf Manual}):
1810 libtool.m4 -----. .--> aclocal.m4 -----.
1811 ltoptions.m4 ---+ .-> aclocal* -+ +--> autoconf*
1812 ltversion.m4 ---+--+ `--> [copy in m4/] --+ |
1813 ltsugar.m4 -----+ | ^ | \/
1814 lt~obsolete.m4 -+ +-> libtoolize* -----' | configure
1815 [ltdl.m4] ------+ | |
1816 `----------------------------------'
1818 ltmain.sh -----------> libtoolize* -> [copy in build-aux/]
1822 During configuration, the @file{libtool} script is generated either
1823 through @command{config.status} or @command{config.lt}:
1827 .--> config.status* --.
1828 configure* --+ +--> libtool
1829 `--> [config.lt*] ----' ^
1831 ltmain.sh --------------------------------'
1835 At @command{make} run time, @command{libtool} is then invoked as needed
1836 as a wrapper around compilers, linkers, install and cleanup programs.
1838 There are alternatives choices to several parts of the setup; for
1839 example, the Libtool macro files can either be copied or symlinked into
1840 the package, or copied into @file{aclocal.m4}. As another example, an
1841 external, pre-configured @command{libtool} script may be used,
1842 by-passing most of the tests and package-specific setup for Libtool.
1845 * Autoconf macros:: Autoconf macros exported by libtool.
1846 * Makefile rules:: Writing @file{Makefile} rules for libtool.
1847 * Using Automake:: Automatically supporting libtool.
1848 * Configuring:: Configuring libtool for a host system.
1849 * Distributing:: What files to distribute with your package.
1850 * Static-only libraries:: Sometimes shared libraries are just a pain.
1853 @node Autoconf macros
1854 @section Autoconf macros exported by libtool
1856 Libtool uses a number of macros to interrogate the host system when it
1857 is being built, and you can use some of them yourself too. Although
1858 there are a great many other macros in the libtool installed m4 files,
1859 these do not form part of the published interface, and are subject to
1860 change between releases.
1863 Macros in the @samp{LT_CMD_} namespace check for various shell
1866 @defmac LT_CMD_MAX_LEN
1867 Finds the longest command line that can be safely passed to
1868 @samp{$SHELL} without being truncated, and store in the shell variable
1869 @samp{$max_cmd_len}. It is only an approximate value, but command
1870 lines of this length or shorter are guaranteed not to be truncated.
1874 Macros in the @samp{LT_FUNC_} namespace check characteristics of
1877 @defmac LT_FUNC_DLSYM_USCORE
1878 @samp{AC_DEFINE} the preprocessor symbol @samp{DLSYM_USCORE} if we
1879 have to add an underscore to symbol-names passed in to @samp{dlsym}.
1883 Macros in the @samp{LT_LIB_} namespace check characteristics of system
1887 Set @samp{LIBM} to the math library or libraries required on this
1891 @defmac LT_LIB_DLLOAD
1892 This is the macro used by @samp{libltdl} to determine which dlloaders
1893 to use on this machine, if any. Several shell variables are set (and
1894 @samp{AC_SUBST}ed) depending on the dlload interfaces are available on
1895 this machine. @samp{LT_DLLOADERS} contains a list of libtool
1896 libraries that can be used, and if necessary also sets
1897 @samp{LIBADD_DLOPEN} if additional system libraries are required by
1898 the @samp{dlopen} loader, and @samp{LIBADD_SHL_LOAD} if additional
1899 system libraries are required by the @samp{shl_load} loader,
1900 respectively. Finally some symbols are set in @file{config.h}
1901 depending on the loaders that are found to work: @samp{HAVE_LIBDL},
1902 @samp{HAVE_SHL_LOAD}, @samp{HAVE_DYLD}, @samp{HAVE_DLD}.
1906 Macros in the @samp{LT_PATH_} namespace search the system for the full
1907 path to particular system commands:
1910 Add a @option{--with-gnu-ld} option to @file{configure}. Try to find
1911 the path to the linker used by @samp{$CC}, and whether it is the
1912 GNU linker. The result is stored in the shell variable
1913 @samp{$LD}, which is @code{AC_SUBST}ed.
1917 Try to find a BSD-compatible @command{nm} or a MS-compatible
1918 @command{dumpbin} command on this machine. The result is stored in the
1919 shell variable @samp{$NM}, which is @code{AC_SUBST}ed.
1923 Macros in the @samp{LT_SYS_} namespace probe for system
1926 @defmac LT_SYS_DLOPEN_SELF
1927 Tests whether a program can dlopen itself, and then also whether the
1928 same program can still dlopen itself when statically linked. Results
1929 are stored in the shell variables @samp{$enable_dlopen_self} and
1930 @samp{enable_dlopen_self_static} respectively.
1933 @defmac LT_SYS_DLOPEN_DEPLIBS
1934 Define the preprocessor symbol @samp{LTDL_DLOPEN_DEPLIBS} if the
1935 OS needs help to load dependent libraries for @samp{dlopen} (or
1939 @defmac LT_SYS_DLSEARCH_PATH
1940 Define the preprocessor symbol @samp{LT_DLSEARCH_PATH} to the system
1941 default library search path.
1944 @defmac LT_SYS_MODULE_EXT
1945 Define the preprocessor symbol @samp{LT_MODULE_EXT} to the extension
1946 used for runtime loadable modules. If you use libltdl to open
1947 modules, then you can simply use the libtool library extension,
1951 @defmac LT_SYS_MODULE_PATH
1952 Define the preprocessor symbol @samp{LT_MODULE_PATH_VAR} to the name
1953 of the shell environment variable that determines the run-time module
1957 @defmac LT_SYS_SYMBOL_USCORE
1958 Set the shell variable @samp{sys_symbol_underscore} to @samp{no}
1959 unless the compiler prefixes global symbols with an underscore.
1963 @node Makefile rules
1964 @section Writing @file{Makefile} rules for libtool
1969 Libtool is fully integrated with Automake (@pxref{Top,, Introduction,
1970 automake, The Automake Manual}), starting with Automake version 1.2.
1972 If you want to use libtool in a regular @file{Makefile} (or
1973 @file{Makefile.in}), you are on your own. If you're not using
1974 Automake, and you don't know how to incorporate libtool into your
1975 package you need to do one of the following:
1979 Download the latest Automake distribution from your nearest GNU
1980 mirror, install it, and start using it.
1983 Learn how to write @file{Makefile} rules by hand. They're sometimes complex,
1984 but if you're clever enough to write rules for compiling your old
1985 libraries, then you should be able to figure out new rules for libtool
1986 libraries (hint: examine the @file{Makefile.in} in the @file{tests/demo}
1987 subdirectory of the libtool distribution@dots{} note especially that it
1988 was automatically generated from the @file{Makefile.am} by Automake).
1991 @node Using Automake
1992 @section Using Automake with libtool
1995 Libtool library support is implemented under the @samp{LTLIBRARIES}
1998 Here are some samples from the Automake @file{Makefile.am} in the
1999 libtool distribution's @file{demo} subdirectory.
2001 First, to link a program against a libtool library, just use the
2002 @samp{program_LDADD}@footnote{@c
2004 Since GNU Automake 1.5, the flags @option{-dlopen}
2005 or @option{-dlpreopen} (@pxref{Link mode}) can be employed with the
2006 @samp{program_LDADD} variable. Unfortunately, older releases didn't
2007 accept these flags, so if you are stuck with an ancient Automake, we
2008 recommend quoting the flag itself, and setting
2009 @samp{program_DEPENDENCIES} too:
2012 program_LDADD = "-dlopen" libfoo.la
2013 program_DEPENDENCIES = libfoo.la
2019 bin_PROGRAMS = hell hell_static
2021 # Build hell from main.c and libhello.la
2022 hell_SOURCES = main.c
2023 hell_LDADD = libhello.la
2025 # Create a statically linked version of hell.
2026 hell_static_SOURCES = main.c
2027 hell_static_LDADD = libhello.la
2028 hell_static_LDFLAGS = -static
2031 You may use the @samp{program_LDFLAGS} variable to stuff in any flags
2032 you want to pass to libtool while linking @file{program} (such as
2033 @option{-static} to avoid linking uninstalled shared libtool libraries).
2035 Building a libtool library is almost as trivial@dots{} note the use of
2036 @samp{libhello_la_LDFLAGS} to pass the @option{-version-info}
2037 (@pxref{Versioning}) option to libtool:
2040 # Build a libtool library, libhello.la for installation in libdir.
2041 lib_LTLIBRARIES = libhello.la
2042 libhello_la_SOURCES = hello.c foo.c
2043 libhello_la_LDFLAGS = -version-info 3:12:1
2046 The @option{-rpath} option is passed automatically by Automake (except for
2047 libraries listed as @code{noinst_LTLIBRARIES}), so you
2048 should not specify it.
2050 @xref{A Shared Library, Building a Shared Library, The Automake Manual,
2051 automake, The Automake Manual}, for more information.
2054 @section Configuring libtool
2055 @cindex configuring libtool
2057 Libtool requires intimate knowledge of your compiler suite and operating
2058 system in order to be able to create shared libraries and link against
2059 them properly. When you install the libtool distribution, a
2060 system-specific libtool script is installed into your binary directory.
2062 However, when you distribute libtool with your own packages
2063 (@pxref{Distributing}), you do not always know the compiler suite and
2064 operating system that are used to compile your package.
2066 For this reason, libtool must be @dfn{configured} before it can be
2067 used. This idea should be familiar to anybody who has used a GNU
2068 @code{configure} script. @code{configure} runs a number of tests for
2069 system features, then generates the @file{Makefile}s (and possibly a
2070 @file{config.h} header file), after which you can run @code{make} and
2073 Libtool adds its own tests to your @code{configure} script in order to
2074 generate a libtool script for the installer's host machine.
2077 * LT_INIT:: Configuring @code{libtool} in @file{configure.ac}.
2078 * Configure notes:: Platform-specific notes for configuration.
2082 @subsection The @code{LT_INIT} macro
2084 If you are using GNU Autoconf (or Automake), you should add a call to
2085 @code{LT_INIT} to your @file{configure.ac} file. This macro
2086 adds many new tests to the @code{configure} script so that the generated
2087 libtool script will understand the characteristics of the host. It's the
2088 most important of a number of macros defined by Libtool:
2090 @defmac LT_PREREQ (@var{version})
2091 Ensure that a recent enough version of Libtool is being used. If the
2092 version of Libtool used for @code{LT_INIT} is earlier than
2093 @var{version}, print an error message to the standard
2094 error output and exit with failure (exit status is 63). For example:
2097 LT_PREREQ([@value{VERSION}])
2101 @defmac LT_INIT (@var{options})
2102 @defmacx AC_PROG_LIBTOOL
2103 @defmacx AM_PROG_LIBTOOL
2104 Add support for the @option{--enable-shared}, @option{--disable-shared},
2105 @option{--enable-static}, @option{--disable-static}, @option{--with-pic}, and
2106 @option{--without-pic} @code{configure} flags.@footnote{@code{LT_INIT} requires
2107 that you define the @file{Makefile} variable @code{top_builddir} in your
2108 @file{Makefile.in}. Automake does this automatically, but Autoconf
2109 users should set it to the relative path to the top of your build
2110 directory (@file{../..}, for example).} @code{AC_PROG_LIBTOOL} and
2111 @code{AM_PROG_LIBTOOL} are deprecated names for older versions of this macro;
2112 @code{autoupdate} will upgrade your @file{configure.ac} files.
2114 By default, this macro turns on shared libraries if they are available,
2115 and also enables static libraries if they don't conflict with the shared
2116 libraries. You can modify these defaults by passing either
2117 @code{disable-shared} or @code{disable-static} in the option list to
2118 @code{LT_INIT}, or using @code{AC_DISABLE_SHARED} or @code{AC_DISABLE_STATIC}.
2121 # Turn off shared libraries during beta-testing, since they
2122 # make the build process take too long.
2123 LT_INIT([disable-shared])
2126 The user may specify modified forms of the configure flags
2127 @option{--enable-shared} and @option{--enable-static} to choose whether
2128 shared or static libraries are built based on the name of the package.
2129 For example, to have shared @samp{bfd} and @samp{gdb} libraries built,
2130 but not shared @samp{libg++}, you can run all three @code{configure}
2134 trick$ ./configure --enable-shared=bfd,gdb
2137 In general, specifying @option{--enable-shared=@var{pkgs}} is the same as
2138 configuring with @option{--enable-shared} every package named in the
2139 comma-separated @var{pkgs} list, and every other package with
2140 @option{--disable-shared}. The @option{--enable-static=@var{pkgs}} flag
2141 behaves similarly, but it uses @option{--enable-static} and
2142 @option{--disable-static}. The same applies to the
2143 @option{--enable-fast-install=@var{pkgs}} flag, which uses
2144 @option{--enable-fast-install} and @option{--disable-fast-install}.
2146 The package name @samp{default} matches any packages that have not set
2147 their name in the @code{PACKAGE} environment variable.
2149 The @option{--with-pic} and @option{--without-pic} configure flags can be used
2150 to specify whether or not @command{libtool} uses PIC objects. By default,
2151 @command{libtool} uses PIC objects for shared libraries and non-PIC objects for
2152 static libraries. The @option{--with-pic} option also accepts a comma-separated
2153 list of package names. Specifying @option{--with-pic=@var{pkgs}} is the same
2154 as configuring every package in @var{pkgs} with @option{--with-pic} and every
2155 other package with the default configuration. The package name @samp{default}
2156 is treated the same as for @option{--enable-shared} and
2157 @option{--enable-static}.
2159 This macro also sets the shell variable @code{LIBTOOL_DEPS}, that you
2160 can use to automatically update the libtool script if it becomes
2161 out-of-date. In order to do that, add to your @file{configure.ac}:
2165 AC_SUBST([LIBTOOL_DEPS])
2168 and, to @file{Makefile.in} or @file{Makefile.am}:
2171 LIBTOOL_DEPS = @@LIBTOOL_DEPS@@
2172 libtool: $(LIBTOOL_DEPS)
2173 $(SHELL) ./config.status libtool
2176 If you are using GNU Automake, you can omit the assignment, as Automake
2177 will take care of it. You'll obviously have to create some dependency
2180 Aside from @code{disable-static} and @code{disable-shared}, there are
2181 other options that you can pass to @code{LT_INIT} to modify its
2182 behaviour. Here is a full list:
2186 Enable checking for dlopen support. This option should be used if
2187 the package makes use of the @option{-dlopen} and @option{-dlpreopen}
2188 libtool flags, otherwise libtool will assume that the system does not
2192 This option should be used if the package has been ported to build clean
2193 dlls on win32 platforms. Usually this means that any library data items
2194 are exported with @code{__declspec(dllexport)} and imported with
2195 @code{__declspec(dllimport)}. If this macro is not used, libtool will
2196 assume that the package libraries are not dll clean and will build only
2197 static libraries on win32 hosts.
2199 Provision must be made to pass @option{-no-undefined} to @code{libtool}
2200 in link mode from the package @code{Makefile}. Naturally, if you pass
2201 @option{-no-undefined}, you must ensure that all the library symbols
2202 @strong{really are} defined at link time!
2204 @item disable-fast-install
2205 Change the default behaviour for @code{LT_INIT} to disable
2206 optimization for fast installation. The user may still override this
2207 default, depending on platform support, by specifying
2208 @option{--enable-fast-install} to @command{configure}.
2211 Change the default behaviour for @code{LT_INIT} to enable
2212 shared libraries. This is the default on all systems where
2213 Libtool knows how to create shared libraries.
2214 The user may still override this default by specifying
2215 @option{--disable-shared} to @command{configure}.
2217 @item disable-shared
2218 Change the default behaviour for @code{LT_INIT} to disable
2219 shared libraries. The user may still override this default by
2220 specifying @option{--enable-shared} to @command{configure}.
2223 Change the default behaviour for @code{LT_INIT} to enable
2224 static libraries. This is the default on all systems where
2225 shared libraries have been disabled for some reason, and on
2226 most systems where shared libraries have been enabled.
2227 If shared libraries are enabled, the user may still override
2228 this default by specifying @option{--disable-static} to
2229 @command{configure}.
2231 @item disable-static
2232 Change the default behaviour for @code{LT_INIT} to disable
2233 static libraries. The user may still override this default by
2234 specifying @option{--enable-static} to @command{configure}.
2237 Change the default behaviour for @command{libtool} to try to use only
2238 PIC objects. The user may still override this default by specifying
2239 @option{--without-pic} to @command{configure}.
2242 Change the default behaviour of @command{libtool} to try to use only
2243 non-PIC objects. The user may still override this default by
2244 specifying @option{--with-pic} to @command{configure}.
2250 @defmac LT_LANG (@var{language})
2251 Enable @command{libtool} support for the language given if it
2252 has not yet already been enabled. Languages accepted are ``C++'',
2253 ``Fortran 77'', ``Java'', ``Go'', and ``Windows Resource''.
2255 If Autoconf language support macros such as @code{AC_PROG_CXX} are
2256 used in your @file{configure.ac}, Libtool language support will automatically
2259 Conversely using @code{LT_LANG} to enable language support for Libtool
2260 will automatically enable Autoconf language support as well.
2262 Both of the following examples are therefore valid ways of adding C++
2263 language support to Libtool.
2277 @defmac AC_LIBTOOL_DLOPEN
2278 This macro is deprecated, the @samp{dlopen} option to @code{LT_INIT} should be
2282 @defmac AC_LIBTOOL_WIN32_DLL
2283 This macro is deprecated, the @samp{win32-dll} option to @code{LT_INIT} should
2287 @defmac AC_DISABLE_FAST_INSTALL
2288 This macro is deprecated, the @samp{disable-fast-install} option to @code{LT_INIT}
2289 should be used instead.
2292 @defmac AC_DISABLE_SHARED
2293 @defmacx AM_DISABLE_SHARED
2294 Change the default behaviour for @code{LT_INIT} to disable shared libraries.
2295 The user may still override this default by specifying @samp{--enable-shared}.
2296 The option @samp{disable-shared} to @code{LT_INIT} is a shorthand for this.
2297 @code{AM_DISABLE_SHARED} is a deprecated alias for @code{AC_DISABLE_SHARED}.
2300 @defmac AC_ENABLE_SHARED
2301 @defmacx AM_ENABLE_SHARED
2302 Change the default behaviour for @code{LT_INIT} to enable shared libraries.
2303 This is the default on all systems where Libtool knows how to create
2304 shared libraries. The user may still override this default by specifying
2305 @samp{--disable-shared}. The option @samp{shared} to @code{LT_INIT} is a
2307 @code{AM_ENABLE_SHARED} is a deprecated alias for @code{AC_ENABLE_SHARED}.
2310 @defmac AC_DISABLE_STATIC
2311 @defmacx AM_DISABLE_STATIC
2312 Change the default behaviour for @code{LT_INIT} to disable static libraries.
2313 The user may still override this default by specifying @samp{--enable-static}.
2314 The option @samp{disable-static} to @code{LT_INIT} is a shorthand for this.
2315 @code{AM_DISABLE_STATIC} is a deprecated alias for @code{AC_DISABLE_STATIC}.
2318 @defmac AC_ENABLE_STATIC
2319 @defmacx AM_ENABLE_STATIC
2320 Change the default behaviour for @code{LT_INIT} to enable static libraries.
2321 This is the default on all systems where shared libraries have been disabled
2322 for some reason, and on most systems where shared libraries have been enabled.
2323 If shared libraries are enabled, the user may still override this default by
2324 specifying @samp{--disable-static}. The option @samp{static} to @code{LT_INIT}
2325 is a shorthand for this.
2326 @code{AM_ENABLE_STATIC} is a deprecated alias for @code{AC_ENABLE_STATIC}.
2329 The tests in @code{LT_INIT} also recognize the following
2330 environment variables:
2333 The C compiler that will be used by the generated @code{libtool}. If
2334 this is not set, @code{LT_INIT} will look for @command{gcc} or
2339 Compiler flags used to generate standard object files. If this is not
2340 set, @code{LT_INIT} will not use any such flags. It affects
2341 only the way @code{LT_INIT} runs tests, not the produced
2346 C preprocessor flags. If this is not set, @code{LT_INIT} will
2347 not use any such flags. It affects only the way @code{LT_INIT}
2348 runs tests, not the produced @code{libtool}.
2352 The system linker to use (if the generated @code{libtool} requires one).
2353 If this is not set, @code{LT_INIT} will try to find out what is
2354 the linker used by @code{CC}.
2358 The flags to be used by @code{libtool} when it links a program. If
2359 this is not set, @code{LT_INIT} will not use any such flags. It
2360 affects only the way @code{LT_INIT} runs tests, not the produced
2365 The libraries to be used by @code{LT_INIT} when it links a
2366 program. If this is not set, @code{LT_INIT} will not use any
2367 such flags. It affects only the way @code{LT_INIT} runs tests,
2368 not the produced @code{libtool}.
2372 Program to use rather than checking for @command{nm}.
2376 Program to use rather than checking for @command{ranlib}.
2380 A command that creates a link of a program, a soft-link if possible, a
2381 hard-link otherwise. @code{LT_INIT} will check for a suitable
2382 program if this variable is not set.
2386 Program to use rather than checking for @command{dlltool}. Only meaningful
2387 for Cygwin/MS-Windows.
2391 Program to use rather than checking for @command{objdump}. Only meaningful
2392 for Cygwin/MS-Windows.
2396 Program to use rather than checking for @command{as}. Only used on
2397 Cygwin/MS-Windows at the moment.
2400 @defvar MANIFEST_TOOL
2401 Program to use rather than checking for @command{mt}, the Manifest Tool.
2402 Only used on Cygwin/MS-Windows at the moment.
2405 With 1.3 era libtool, if you wanted to know any details of what
2406 libtool had discovered about your architecture and environment, you
2407 had to run the script with @option{--config} and grep through the
2408 results. This idiom was supported up to and including 1.5.x era
2409 libtool, where it was possible to call the generated libtool script
2410 from @file{configure.ac} as soon as @code{LT_INIT} had
2411 completed. However, one of the features of libtool 1.4 was that the
2412 libtool configuration was migrated out of a separate @file{ltconfig}
2413 file, and added to the @code{LT_INIT} macro (nee @code{AC_PROG_LIBTOOL}),
2414 so the results of the configuration tests were available directly to code in
2415 @file{configure.ac}, rendering the call out to the generated libtool
2418 Starting with libtool 2.0, the multipass generation of the libtool
2419 script has been consolidated into a single @file{config.status} pass,
2420 which happens after all the code in @file{configure.ac} has
2421 completed. The implication of this is that the libtool script does
2422 not exist during execution of code from @file{configure.ac}, and so
2423 obviously it cannot be called for @option{--config} details anymore. If
2424 you are upgrading projects that used this idiom to libtool 2.0 or
2425 newer, you should replace those calls with direct references to the
2426 equivalent Autoconf shell variables that are set by the configure time
2427 tests before being passed to @file{config.status} for inclusion in the
2428 generated libtool script.
2431 By default, the configured @file{libtool} script is generated by the
2432 call to @code{AC_OUTPUT} command, and there is rarely any need to use
2433 @file{libtool} from @file{configure}. However, sometimes it is
2434 necessary to run configure time compile and link tests using
2435 @file{libtool}. You can add @code{LT_OUTPUT} to your
2436 @file{configure.ac} any time after @code{LT_INIT} and any
2437 @code{LT_LANG} calls; that done, @file{libtool} will be created by a
2438 specially generated @file{config.lt} file, and available for use in
2441 Also, when @code{LT_OUTPUT} is used, for backwards compatibility with
2442 Automake regeneration rules, @file{config.status} will call
2443 @file{config.lt} to regenerate @file{libtool}, rather than generating
2448 When you invoke the @command{libtoolize} program (@pxref{Invoking
2449 libtoolize}), it will tell you where to find a definition of
2450 @code{LT_INIT}. If you use Automake, the @command{aclocal} program
2451 will automatically add @code{LT_INIT} support to your
2452 @file{configure} script when it sees the invocation of @code{LT_INIT}
2453 in @file{configure.ac}.
2455 Because of these changes, and the runtime version compatibility checks
2456 Libtool now executes, we now advise @strong{against} including a copy of
2457 @file{libtool.m4} (and brethren) in @file{acinclude.m4}. Instead,
2458 you should set your project macro directory with
2459 @code{AC_CONFIG_MACRO_DIR}. When you @command{libtoolize} your
2460 project, a copy of the relevant macro definitions will be placed in
2461 your @code{AC_CONFIG_MACRO_DIR}, where @command{aclocal} can reference
2462 them directly from @file{aclocal.m4}.
2465 @node Configure notes
2466 @subsection Platform-specific configuration notes
2468 While Libtool tries to hide as many platform-specific features as possible,
2469 some have to be taken into account when configuring either the Libtool package
2470 or a libtoolized package.
2476 @section Including libtool in your package
2478 In order to use libtool, you need to include the following files with
2483 @pindex config.guess
2484 Attempt to guess a canonical system name.
2488 Canonical system name validation subroutine script.
2492 BSD-compatible @command{install} replacement script.
2496 A generic script implementing basic libtool functionality.
2499 Note that the libtool script itself should @emph{not} be included with
2500 your package. @xref{Configuring}.
2502 You should use the @command{libtoolize} program, rather than manually
2503 copying these files into your package.
2506 * Invoking libtoolize:: @code{libtoolize} command line options.
2507 * Autoconf and LTLIBOBJS:: Autoconf automates LTLIBOBJS generation.
2510 @node Invoking libtoolize
2511 @subsection Invoking @command{libtoolize}
2513 @cindex libtoolize command options
2514 @cindex command options, libtoolize
2515 @cindex options, libtoolize command
2517 The @command{libtoolize} program provides a standard way to add libtool
2518 support to your package. In the future, it may implement better usage
2519 checking, or other features to make libtool even easier to use.
2521 The @command{libtoolize} program has the following synopsis:
2524 libtoolize [@var{option}]@dots{}
2528 and accepts the following options:
2534 Copy files from the libtool data directory rather than creating
2538 Dump a trace of shell script execution to standard output. This
2539 produces a lot of output, so you may wish to pipe it to @command{less} (or
2540 @command{more}) or redirect to a file.
2544 Don't run any commands that modify the file system, just print them
2549 Replace existing libtool files. By default, @command{libtoolize} won't
2550 overwrite existing files.
2553 Display a help message and exit.
2555 @item --ltdl [@var{target-directory-name}]
2556 Install libltdl in the @var{target-directory-name} subdirectory of
2557 your package. Normally, the directory is extracted from the argument
2558 to @code{LT_CONFIG_LTDL_DIR} in @file{configure.ac}, though you can
2559 also specify a subdirectory name here if you are not using Autoconf
2560 for example. If @command{libtoolize} can't determine the target
2561 directory, @samp{libltdl} is used as the default.
2564 Normally, Libtoolize tries to diagnose use of deprecated libtool macros
2565 and other stylistic issues. If you are deliberately using outdated
2566 calling conventions, this option prevents Libtoolize from explaining
2567 how to update your project's Libtool conventions.
2569 @item --nonrecursive
2570 If passed in conjunction with @option{--ltdl}, this option will cause
2571 the @command{libltdl} installed by @samp{libtoolize} to be set up for
2572 use with a non-recursive @command{automake} build. To make use of it,
2573 you will need to add the following to the @file{Makefile.am} of the
2577 ## libltdl/Makefile.inc @r{appends to the following variables}
2578 ## @r{so we set them here before including it:}
2585 noinst_LTLIBRARIES =
2594 include libltdl/Makefile.inc
2601 Work silently. @samp{libtoolize --quiet} is used by GNU Automake
2602 to add libtool files to your package if necessary.
2605 If passed in conjunction with @option{--ltdl}, this option will cause
2606 the @command{libtoolize} installed @samp{libltdl} to be set up for use
2607 with a recursive @command{automake} build. To make use of it, you
2608 will need to adjust the parent project's @file{configure.ac}:
2611 AC_CONFIG_FILES([libltdl/Makefile])
2615 and @file{Makefile.am}:
2622 If passed in conjunction with @option{--ltdl}, this option will cause
2623 the @command{libtoolize} installed @samp{libltdl} to be set up for
2624 independent configuration and compilation as a self-contained
2625 subproject. To make use of it, you should arrange for your build to
2626 call @command{libltdl/configure}, and then run @command{make} in the
2627 @file{libltdl} directory (or the subdirectory you put libltdl into).
2628 If your project uses Autoconf, you can use the supplied
2629 @samp{LT_WITH_LTDL} macro, or else call @samp{AC_CONFIG_SUBDIRS}
2632 Previous releases of @samp{libltdl} built exclusively in this mode,
2633 but now it is the default mode both for backwards compatibility and
2634 because, for example, it is suitable for use in projects that wish to
2635 use @samp{libltdl}, but not use the Autotools for their own build
2640 Work noisily! Give a blow by blow account of what
2641 @command{libtoolize} is doing.
2644 Print @command{libtoolize} version information and exit.
2647 @cindex LIBTOOLIZE_OPTIONS
2648 Sometimes it can be useful to pass options to @command{libtoolize} even
2649 though it is called by another program, such as @command{autoreconf}. A
2650 limited number of options are parsed from the environment variable
2651 @code{LIBTOOLIZE_OPTIONS}: currently @option{--debug}, @option{--no-warn},
2652 @option{--quiet} and @option{--verbose}. Multiple options passed in
2653 @code{LIBTOOLIZE_OPTIONS} must be separated with a space, comma or a
2656 By default, a warning is issued for unknown options found in
2657 @code{LIBTOOLIZE_OPTIONS} unless the first such option is
2658 @option{--no-warn}. Where @command{libtoolize} has always quit
2659 on receipt of an unknown option at the command line, this and all
2660 previous releases of @command{libtoolize} will continue unabated whatever
2661 the content of @code{LIBTOOLIZE_OPTIONS} (modulo some possible warning
2665 trick$ @kbd{LIBTOOLIZE_OPTIONS=--no-warn,--quiet autoreconf --install}
2668 @findex AC_CONFIG_MACRO_DIR
2669 If @command{libtoolize} detects an explicit call to
2670 @code{AC_CONFIG_MACRO_DIR} (@pxref{Input, , The Autoconf Manual,
2671 autoconf, The Autoconf Manual}) in your @file{configure.ac}, it will
2672 put the Libtool macros in the specified directory.
2674 In the future other Autotools will automatically check the contents of
2675 @code{AC_CONFIG_MACRO_DIR}, but at the moment it is more portable to
2676 add the macro directory to @code{ACLOCAL_AMFLAGS} in
2677 @file{Makefile.am}, which is where the tools currently look. If
2678 @command{libtoolize} doesn't see @code{AC_CONFIG_MACRO_DIR}, it too
2679 will honour the first @samp{-I} argument in @code{ACLOCAL_AMFLAGS}
2680 when choosing a directory to store libtool configuration macros in.
2681 It is perfectly sensible to use both @code{AC_CONFIG_MACRO_DIR} and
2682 @code{ACLOCAL_AMFLAGS}, as long as they are kept in synchronisation.
2685 ACLOCAL_AMFLAGS = -I m4
2688 When you bootstrap your project with @command{aclocal}, then you will
2689 need to explicitly pass the same macro directory with
2690 @command{aclocal}'s @samp{-I} flag:
2693 trick$ @kbd{aclocal -I m4}
2696 @findex AC_CONFIG_AUX_DIR
2697 If @command{libtoolize} detects an explicit call to
2698 @code{AC_CONFIG_AUX_DIR} (@pxref{Input, , The Autoconf Manual,
2699 autoconf, The Autoconf Manual}) in your @file{configure.ac}, it
2700 will put the other support files in the specified directory.
2701 Otherwise they too end up in the project root directory.
2703 Unless @option{--no-warn} is passed, @command{libtoolize} displays
2704 hints for adding libtool support to your package, as well.
2706 @node Autoconf and LTLIBOBJS
2707 @subsection Autoconf and @code{LTLIBOBJS}
2709 People used to add code like the following to their
2710 @file{configure.ac}:
2714 LTLIBOBJS=`echo "$LIBOBJS" | sed 's/\.[^.]* /.lo /g;s/\.[^.]*$/.lo/'`
2715 AC_SUBST([LTLIBOBJS])
2719 This is no longer required (since Autoconf 2.54), and doesn't take
2720 Automake's deansification support into account either, so doesn't work
2721 correctly even with ancient Autoconfs!
2723 Provided you are using a recent (2.54 or better) incarnation of
2724 Autoconf, the call to @code{AC_OUTPUT} takes care of setting
2725 @code{LTLIBOBJS} up correctly, so you can simply delete such snippets
2726 from your @file{configure.ac} if you had them.
2729 @node Static-only libraries
2730 @section Static-only libraries
2731 @cindex debugging libraries
2732 @cindex developing libraries
2733 @cindex double-compilation, avoiding
2734 @cindex avoiding shared libraries
2735 @cindex eliding shared libraries
2736 @cindex using shared libraries, not
2737 @cindex shared libraries, not using
2738 @cindex time, saving
2741 When you are developing a package, it is often worthwhile to configure
2742 your package with the @option{--disable-shared} flag, or to override the
2743 defaults for @code{LT_INIT} by using the @code{disable-shared} option
2744 (@pxref{LT_INIT, , The @code{LT_INIT} macro}). This prevents libtool
2745 from building shared libraries, which has several advantages:
2749 compilation is twice as fast, which can speed up your development cycle,
2752 debugging is easier because you don't need to deal with any complexities
2753 added by shared libraries, and
2756 you can see how libtool behaves on static-only platforms.
2759 You may want to put a small note in your package @file{README} to let
2760 other developers know that @option{--disable-shared} can save them time.
2761 The following example note is taken from the GIMP@footnote{GNU Image
2762 Manipulation Program, for those who haven't taken the plunge. See
2763 @url{http://www.gimp.org/}.} distribution @file{README}:
2766 The GIMP uses GNU Libtool in order to build shared libraries on a
2767 variety of systems. While this is very nice for making usable
2768 binaries, it can be a pain when trying to debug a program. For that
2769 reason, compilation of shared libraries can be turned off by
2770 specifying the @option{--disable-shared} option to @file{configure}.
2774 @node Other languages
2775 @chapter Using libtool with other languages
2776 @cindex C, not using
2777 @cindex languages, non-C
2780 Libtool was first implemented in order to add support for writing shared
2781 libraries in the C language. However, over time, libtool is being
2782 integrated with other languages, so that programmers are free to reap
2783 the benefits of shared libraries in their favorite programming language.
2785 This chapter describes how libtool interacts with other languages,
2786 and what special considerations you need to make if you do not use C.
2789 * C++ libraries:: Writing libraries for C++
2794 @section Writing libraries for C++
2795 @c FIXME: in the TOC, the ++ is too large (seems to be math mode)
2796 @cindex trouble with C++
2797 @cindex pitfalls using C++
2798 @cindex C++, pitfalls
2800 Creating libraries of C++ code should be a fairly straightforward
2801 process, because its object files differ from C ones in only three ways:
2805 Because of name mangling, C++ libraries are only usable by the C++
2806 compiler that created them. This decision was made by the designers of
2807 C++ in order to protect users from conflicting implementations of
2808 features such as constructors, exception handling, and RTTI.
2811 On some systems, the C++ compiler must take special actions for the
2812 dynamic linker to run dynamic (i.e., run-time) initializers. This means
2813 that we should not call @command{ld} directly to link such libraries, and
2814 we should use the C++ compiler instead.
2817 C++ compilers will link some Standard C++ library in by default, but
2818 libtool does not know which are these libraries, so it cannot even run
2819 the inter-library dependence analyzer to check how to link it in.
2820 Therefore, running @command{ld} to link a C++ program or library is deemed
2824 Because of these three issues, Libtool has been designed to always use
2825 the C++ compiler to compile and link C++ programs and libraries. In
2826 some instances the @code{main()} function of a program must also be
2827 compiled with the C++ compiler for static C++ objects to be properly
2833 @cindex language names
2834 @cindex inferring tags
2836 Libtool supports multiple languages through the use of tags. Technically
2837 a tag corresponds to a set of configuration variables associated with a
2838 language. These variables tell @command{libtool} how it should create
2839 objects and libraries for each language.
2841 Tags are defined at @command{configure}-time for each language activated
2842 in the package (see @code{LT_LANG} in @ref{LT_INIT}). Here is the
2843 correspondence between language names and tags names.
2845 @multitable {Windows Resource} {Tag name}
2846 @item Language name @tab Tag name
2850 @item Fortran 77 @tab F77
2851 @item Fortran @tab FC
2853 @item Windows Resource @tab RC
2856 @command{libtool} tries to automatically infer which tag to use from
2857 the compiler command being used to compile or link. If it can't infer
2858 a tag, then it defaults to the configuration for the @code{C} language.
2860 The tag can also be specified using @command{libtool}'s
2861 @option{--tag=@var{tag}} option (@pxref{Invoking libtool}). It is a good
2862 idea to do so in @file{Makefile} rules, because that will allow users to
2863 substitute the compiler without relying on @command{libtool} inference
2864 heuristics. When no tag is specified, @command{libtool} will default
2865 to @code{CC}; this tag always exists.
2867 Finally, the set of tags available in a particular project can be
2868 retrieved by tracing for the @code{LT_SUPPORTED_TAG} macro (@pxref{Trace
2872 @chapter Library interface versions
2873 @cindex dynamic dependencies
2874 @cindex dependency versioning
2875 @cindex shared library versions
2877 The most difficult issue introduced by shared libraries is that of
2878 creating and resolving runtime dependencies. Dependencies on programs
2879 and libraries are often described in terms of a single name, such as
2880 @command{sed}. So, one may say ``libtool depends on sed,'' and that is
2881 good enough for most purposes.
2883 However, when an interface changes regularly, we need to be more
2884 specific: ``Gnus 5.1 requires Emacs 19.28 or above.'' Here, the
2885 description of an interface consists of a name, and a ``version
2888 Even that sort of description is not accurate enough for some purposes.
2889 What if Emacs 20 changes enough to break Gnus 5.1?
2891 The same problem exists in shared libraries: we require a formal version
2892 system to describe the sorts of dependencies that programs have on
2893 shared libraries, so that the dynamic linker can guarantee that programs
2894 are linked only against libraries that provide the interface they
2898 * Interfaces:: What are library interfaces?
2899 * Libtool versioning:: Libtool's versioning system.
2900 * Updating version info:: Changing version information before releases.
2901 * Release numbers:: Breaking binary compatibility for aesthetics.
2905 @section What are library interfaces?
2906 @cindex library interfaces
2908 Interfaces for libraries may be any of the following (and more):
2912 global variables: both names and types
2915 global functions: argument types and number, return types, and function names
2918 standard input, standard output, standard error, and file formats
2921 sockets, pipes, and other inter-process communication protocol formats
2924 Note that static functions do not count as interfaces, because they are
2925 not directly available to the user of the library.
2927 @node Libtool versioning
2928 @section Libtool's versioning system
2929 @cindex libtool library versions
2930 @cindex formal versioning
2931 @cindex versioning, formal
2933 Libtool has its own formal versioning system. It is not as flexible as
2934 some, but it is definitely the simplest of the more powerful versioning
2937 Think of a library as exporting several sets of interfaces, arbitrarily
2938 represented by integers. When a program is linked against a library, it
2939 may use any subset of those interfaces.
2941 Libtool's description of the interfaces that a program uses is simple:
2942 it encodes the least and the greatest interface numbers in the resulting
2943 binary (@var{first-interface}, @var{last-interface}).
2945 The dynamic linker is guaranteed that if a library supports @emph{every}
2946 interface number between @var{first-interface} and @var{last-interface},
2947 then the program can be relinked against that library.
2949 Note that this can cause problems because libtool's compatibility
2950 requirements are actually stricter than is necessary.
2952 Say @file{libhello} supports interfaces 5, 16, 17, 18, and 19, and that
2953 libtool is used to link @file{test} against @file{libhello}.
2955 Libtool encodes the numbers 5 and 19 in @file{test}, and the dynamic
2956 linker will only link @file{test} against libraries that support
2957 @emph{every} interface between 5 and 19. So, the dynamic linker refuses
2958 to link @file{test} against @file{libhello}!
2960 In order to eliminate this problem, libtool only allows libraries to
2961 declare consecutive interface numbers. So, @file{libhello} can declare at
2962 most that it supports interfaces 16 through 19. Then, the dynamic
2963 linker will link @file{test} against @file{libhello}.
2965 So, libtool library versions are described by three integers:
2969 The most recent interface number that this library implements.
2972 The implementation number of the @var{current} interface.
2975 The difference between the newest and oldest interfaces that this
2976 library implements. In other words, the library implements all the
2977 interface numbers in the range from number @code{@var{current} -
2978 @var{age}} to @code{@var{current}}.
2981 If two libraries have identical @var{current} and @var{age} numbers,
2982 then the dynamic linker chooses the library with the greater
2983 @var{revision} number.
2985 @node Updating version info
2986 @section Updating library version information
2988 If you want to use libtool's versioning system, then you must specify
2989 the version information to libtool using the @option{-version-info} flag
2990 during link mode (@pxref{Link mode}).
2992 This flag accepts an argument of the form
2993 @samp{@var{current}[:@var{revision}[:@var{age}]]}. So, passing
2994 @option{-version-info 3:12:1} sets @var{current} to 3, @var{revision} to
2995 12, and @var{age} to 1.
2997 If either @var{revision} or @var{age} are omitted, they default to 0.
2998 Also note that @var{age} must be less than or equal to the @var{current}
3001 Here are a set of rules to help you update your library version
3006 Start with version information of @samp{0:0:0} for each libtool library.
3009 Update the version information only immediately before a public release
3010 of your software. More frequent updates are unnecessary, and only
3011 guarantee that the current interface number gets larger faster.
3014 If the library source code has changed at all since the last update,
3015 then increment @var{revision} (@samp{@var{c}:@var{r}:@var{a}} becomes
3016 @samp{@var{c}:@math{r+1}:@var{a}}).
3019 If any interfaces have been added, removed, or changed since the last
3020 update, increment @var{current}, and set @var{revision} to 0.
3023 If any interfaces have been added since the last public release, then
3024 increment @var{age}.
3027 If any interfaces have been removed or changed since the last public
3028 release, then set @var{age} to 0.
3031 @strong{@emph{Never}} try to set the interface numbers so that they
3032 correspond to the release number of your package. This is an abuse that
3033 only fosters misunderstanding of the purpose of library versions.
3034 Instead, use the @option{-release} flag (@pxref{Release numbers}), but be
3035 warned that every release of your package will not be binary compatible
3036 with any other release.
3038 The following explanation may help to understand the above rules a bit
3039 better: consider that there are three possible kinds of reactions from
3040 users of your library to changes in a shared library:
3044 Programs using the previous version may use the new version as
3045 drop-in replacement, and programs using the new version can also work
3046 with the previous one. In other words, no recompiling nor relinking
3047 is needed. In this case, bump @var{revision} only, don't touch
3048 @var{current} nor @var{age}.
3051 Programs using the previous version may use the new version as
3052 drop-in replacement, but programs using the new version may use APIs not
3053 present in the previous one. In other words, a program linking against
3054 the new version may fail with ``unresolved symbols'' if linking against
3055 the old version at runtime: set @var{revision} to 0, bump @var{current}
3059 Programs may need to be changed, recompiled, relinked in order to use
3060 the new version. Bump @var{current}, set @var{revision} and @var{age}
3065 In the above description, @emph{programs} using the library in question
3066 may also be replaced by other libraries using it.
3069 @node Release numbers
3070 @section Managing release information
3072 Often, people want to encode the name of the package release into the
3073 shared library so that it is obvious to the user which package their
3074 programs are linked against. This convention is used especially on
3078 trick$ @kbd{ls /usr/lib/libbfd*}
3079 /usr/lib/libbfd.a /usr/lib/libbfd.so.2.7.0.2
3084 On @samp{trick}, @file{/usr/lib/libbfd.so} is a symbolic link to
3085 @file{libbfd.so.2.7.0.2}, which was distributed as a part of
3086 @samp{binutils-2.7.0.2}.
3088 Unfortunately, this convention conflicts directly with libtool's idea of
3089 library interface versions, because the library interface rarely changes
3090 at the same time that the release number does, and the library suffix is
3091 never the same across all platforms.
3093 So, in order to accommodate both views, you can use the @option{-release}
3094 flag in order to set release information for libraries for which you do not
3095 want to use @option{-version-info}. For the @file{libbfd} example, the
3096 next release that uses libtool should be built with @samp{-release
3097 2.9.0}, which will produce the following files on GNU/Linux:
3100 trick$ @kbd{ls /usr/lib/libbfd*}
3101 /usr/lib/libbfd-2.9.0.so /usr/lib/libbfd.a
3106 In this case, @file{/usr/lib/libbfd.so} is a symbolic link to
3107 @file{libbfd-2.9.0.so}. This makes it obvious that the user is dealing
3108 with @samp{binutils-2.9.0}, without compromising libtool's idea of
3111 Note that this option causes a modification of the library name, so do
3112 not use it unless you want to break binary compatibility with any past
3113 library releases. In general, you should only use @option{-release} for
3114 package-internal libraries or for ones whose interfaces change very
3118 @chapter Tips for interface design
3119 @cindex library interfaces, design
3120 @cindex design of library interfaces
3122 Writing a good library interface takes a lot of practice and thorough
3123 understanding of the problem that the library is intended to solve.
3125 If you design a good interface, it won't have to change often, you won't
3126 have to keep updating documentation, and users won't have to keep
3127 relearning how to use the library.
3129 Here is a brief list of tips for library interface design that may
3130 help you in your exploits:
3134 Try to make every interface truly minimal, so that you won't need to
3135 delete entry points very often.
3137 @item Avoid interface changes
3138 @cindex renaming interface functions
3139 Some people love redesigning and changing entry points just for the heck
3140 of it (note: @emph{renaming} a function is considered changing an entry
3141 point). Don't be one of those people. If you must redesign an
3142 interface, then try to leave compatibility functions behind so that
3143 users don't need to rewrite their existing code.
3145 @item Use opaque data types
3146 @cindex opaque data types
3147 The fewer data type definitions a library user has access to, the
3148 better. If possible, design your functions to accept a generic pointer
3149 (that you can cast to an internal data type), and provide access
3150 functions rather than allowing the library user to directly manipulate
3152 That way, you have the freedom to change the data structures without
3153 changing the interface.
3155 This is essentially the same thing as using abstract data types and
3156 inheritance in an object-oriented system.
3158 @item Use header files
3159 @cindex header files
3160 If you are careful to document each of your library's global functions
3161 and variables in header files, and include them in your library source
3162 files, then the compiler will let you know if you make any interface
3163 changes by accident (@pxref{C header files}).
3165 @item Use the @code{static} keyword (or equivalent) whenever possible
3166 @cindex global functions
3167 The fewer global functions your library has, the more flexibility you'll
3168 have in changing them. Static functions and variables may change forms
3169 as often as you like@dots{} your users cannot access them, so they
3170 aren't interface changes.
3172 @item Be careful with array dimensions
3173 The number of elements in a global array is part of an interface, even
3174 if the header just declares @code{extern int foo[];}. This is because
3175 on i386 and some other SVR4/ELF systems, when an application
3176 references data in a shared library the size of that data (whatever
3177 its type) is included in the application executable. If you might
3178 want to change the size of an array or string then provide a pointer
3179 not the actual array.
3183 * C header files:: How to write portable include files.
3186 @node C header files
3187 @section Writing C header files
3188 @cindex portable C headers
3189 @cindex C header files, portable
3190 @cindex include files, portable
3192 Writing portable C header files can be difficult, since they may be read
3193 by different types of compilers:
3197 C++ compilers require that functions be declared with full prototypes,
3198 since C++ is more strongly typed than C@. C functions and variables also
3199 need to be declared with the @code{extern "C"} directive, so that the
3200 names aren't mangled. @xref{C++ libraries}, for other issues relevant
3201 to using C++ with libtool.
3203 @item ANSI C compilers
3204 ANSI C compilers are not as strict as C++ compilers, but functions
3205 should be prototyped to avoid unnecessary warnings when the header file
3206 is @code{#include}d.
3208 @item non-ANSI C compilers
3209 Non-ANSI compilers will report errors if functions are prototyped.
3212 These complications mean that your library interface headers must use
3213 some C preprocessor magic in order to be usable by each of the above
3216 @file{foo.h} in the @file{tests/demo} subdirectory of the libtool
3217 distribution serves as an example for how to write a header file that
3218 can be safely installed in a system directory.
3220 Here are the relevant portions of that file:
3223 /* BEGIN_C_DECLS should be used at the beginning of your declarations,
3224 so that C++ compilers don't mangle their names. Use END_C_DECLS at
3225 the end of C declarations. */
3226 #undef BEGIN_C_DECLS
3229 # define BEGIN_C_DECLS extern "C" @{
3230 # define END_C_DECLS @}
3232 # define BEGIN_C_DECLS /* empty */
3233 # define END_C_DECLS /* empty */
3236 /* PARAMS is a macro used to wrap function prototypes, so that
3237 compilers that don't understand ANSI C prototypes still work,
3238 and ANSI C compilers can issue warnings about type mismatches. */
3240 #if defined (__STDC__) || defined (_AIX) \
3241 || (defined (__mips) && defined (_SYSTYPE_SVR4)) \
3242 || defined(WIN32) || defined(__cplusplus)
3243 # define PARAMS(protos) protos
3245 # define PARAMS(protos) ()
3249 These macros are used in @file{foo.h} as follows:
3255 /* The above macro definitions. */
3260 int foo PARAMS((void));
3261 int hello PARAMS((void));
3268 Note that the @file{#ifndef FOO_H} prevents the body of @file{foo.h}
3269 from being read more than once in a given compilation.
3271 Also the only thing that must go outside the
3272 @code{BEGIN_C_DECLS}/@code{END_C_DECLS} pair are @code{#include} lines.
3273 Strictly speaking it is only C symbol names that need to be protected,
3274 but your header files will be more maintainable if you have a single
3275 pair of these macros around the majority of the header contents.
3277 You should use these definitions of @code{PARAMS}, @code{BEGIN_C_DECLS},
3278 and @code{END_C_DECLS} into your own headers. Then, you may use them to
3279 create header files that are valid for C++, ANSI, and non-ANSI
3280 compilers@footnote{We used to recommend @code{__P},
3281 @code{__BEGIN_DECLS} and @code{__END_DECLS}. This was bad advice since
3282 symbols (even preprocessor macro names) that begin with an underscore
3283 are reserved for the use of the compiler.}.
3285 Do not be naive about writing portable code. Following the tips given
3286 above will help you miss the most obvious problems, but there are
3287 definitely other subtle portability issues. You may need to cope with
3288 some of the following issues:
3292 Pre-ANSI compilers do not always support the @code{void *} generic
3293 pointer type, and so need to use @code{char *} in its place.
3296 The @code{const}, @code{inline} and @code{signed} keywords are not
3297 supported by some compilers, especially pre-ANSI compilers.
3300 The @code{long double} type is not supported by many compilers.
3304 @node Inter-library dependencies
3305 @chapter Inter-library dependencies
3306 @cindex dependencies between libraries
3307 @cindex inter-library dependencies
3309 By definition, every shared library system provides a way for
3310 executables to depend on libraries, so that symbol resolution is
3311 deferred until runtime.
3313 An @dfn{inter-library dependency} is one in which a library depends on
3314 other libraries. For example, if the libtool library @file{libhello}
3315 uses the @code{cos} function, then it has an inter-library dependency
3316 on @file{libm}, the math library that implements @code{cos}.
3318 Some shared library systems provide this feature in an
3319 internally-consistent way: these systems allow chains of dependencies of
3320 potentially infinite length.
3322 However, most shared library systems are restricted in that they only
3323 allow a single level of dependencies. In these systems, programs may
3324 depend on shared libraries, but shared libraries may not depend on other
3327 In any event, libtool provides a simple mechanism for you to declare
3328 inter-library dependencies: for every library @file{lib@var{name}} that
3329 your own library depends on, simply add a corresponding
3330 @code{-l@var{name}} option to the link line when you create your
3331 library. To make an example of our @file{libhello} that depends on
3335 burger$ @kbd{libtool --mode=link gcc -g -O -o libhello.la foo.lo hello.lo \
3336 -rpath /usr/local/lib -lm}
3340 When you link a program against @file{libhello}, you don't need to
3341 specify the same @samp{-l} options again: libtool will do that for you,
3342 in order to guarantee that all the required libraries are found. This
3343 restriction is only necessary to preserve compatibility with static
3344 library systems and simple dynamic library systems.
3346 Some platforms, such as Windows, do not even allow you this
3347 flexibility. In order to build a shared library, it must be entirely
3348 self-contained or it must have dependencies known at link time (that is,
3349 have references only to symbols that are found in the @file{.lo} files
3350 or the specified @samp{-l} libraries), and you need to specify the
3351 @option{-no-undefined} flag. By default, libtool builds only static
3352 libraries on these kinds of platforms.
3354 The simple-minded inter-library dependency tracking code of libtool
3355 releases prior to 1.2 was disabled because it was not clear when it was
3356 possible to link one library with another, and complex failures would
3357 occur. A more complex implementation of this concept was re-introduced
3358 before release 1.3, but it has not been ported to all platforms that
3359 libtool supports. The default, conservative behavior is to avoid
3360 linking one library with another, introducing their inter-dependencies
3361 only when a program is linked with them.
3363 @node Dlopened modules
3364 @chapter Dlopened modules
3369 @cindex dynamic linking, applications
3370 @cindex dlopening modules
3371 @cindex modules, dynamic
3372 @cindex application-level dynamic linking
3374 It can sometimes be confusing to discuss @dfn{dynamic linking}, because
3375 the term is used to refer to two different concepts:
3379 Compiling and linking a program against a shared library, which is
3380 resolved automatically at run time by the dynamic linker. In this
3381 process, dynamic linking is transparent to the application.
3384 The application calling functions such as @code{dlopen} that load
3385 arbitrary, user-specified modules at runtime. This type of dynamic
3386 linking is explicitly controlled by the application.
3389 To mitigate confusion, this manual refers to the second type of dynamic
3390 linking as @dfn{dlopening} a module.
3392 The main benefit to dlopening object modules is the ability to access
3393 compiled object code to extend your program, rather than using an
3394 interpreted language. In fact, dlopen calls are frequently used in
3395 language interpreters to provide an efficient way to extend the
3398 Libtool provides support for dlopened modules. However, you should
3399 indicate that your package is willing to use such support, by using the
3400 @code{LT_INIT} option @samp{dlopen} in @file{configure.ac}. If this
3401 option is not given, libtool will assume no dlopening mechanism is
3402 available, and will try to simulate it.
3404 This chapter discusses how you as a dlopen application developer might
3405 use libtool to generate dlopen-accessible modules.
3408 * Building modules:: Creating dlopenable objects and libraries.
3409 * Dlpreopening:: Dlopening that works on static platforms.
3410 * Linking with dlopened modules:: Using dlopenable modules in libraries.
3411 * Finding the dlname:: Choosing the right file to @code{dlopen}.
3412 * Dlopen issues:: Unresolved problems that need your attention.
3415 @node Building modules
3416 @section Building modules to dlopen
3418 On some operating systems, a program symbol must be specially declared
3419 in order to be dynamically resolved with the @code{dlsym} (or
3420 equivalent) function. Libtool provides the @option{-export-dynamic} and
3421 @option{-module} link flags (@pxref{Link mode}), for you to make that
3422 declaration. You need to use these flags if you are linking an
3423 application program that dlopens other modules or a libtool library
3424 that will also be dlopened.
3426 For example, if we wanted to build a shared library, @file{hello},
3427 that would later be dlopened by an application, we would add
3428 @option{-module} to the other link flags:
3431 burger$ @kbd{libtool --mode=link gcc -module -o hello.la foo.lo \
3432 hello.lo -rpath /usr/local/lib -lm}
3436 If symbols from your @emph{executable} are needed to satisfy unresolved
3437 references in a library you want to dlopen you will have to use the flag
3438 @option{-export-dynamic}. You should use @option{-export-dynamic} while
3439 linking the executable that calls dlopen:
3442 burger$ @kbd{libtool --mode=link gcc -export-dynamic -o helldl main.o}
3447 @section Dlpreopening
3449 Libtool provides special support for dlopening libtool object and
3450 libtool library files, so that their symbols can be resolved
3451 @emph{even on platforms without any @code{dlopen} and @code{dlsym}
3454 Consider the following alternative ways of loading code into your
3455 program, in order of increasing ``laziness'':
3459 Linking against object files that become part of the program executable,
3460 whether or not they are referenced. If an object file cannot be found,
3461 then the compile time linker refuses to create the executable.
3464 Declaring a static library to the linker, so that it is searched at link
3465 time in order to satisfy any undefined references in the above object
3466 files. If the static library cannot be found, then the compile time
3467 linker refuses to create the executable.
3470 Declaring a shared library to the runtime linker, so that it is searched
3471 at runtime in order to satisfy any undefined references in the above
3472 files. If the shared library cannot be found, then the dynamic linker
3473 aborts the program before it runs.
3476 Dlopening a module, so that the application can resolve its own,
3477 dynamically-computed references. If there is an error opening the
3478 module, or the module is not found, then the application can recover
3482 Libtool emulates @option{-dlopen} on static platforms by linking objects
3483 into the program at compile time, and creating data structures that
3484 represent the program's symbol table. In order to use this feature,
3485 you must declare the objects you want your application to dlopen by
3486 using the @option{-dlopen} or @option{-dlpreopen} flags when you link your
3487 program (@pxref{Link mode}).
3489 @deftp {Data Type} {lt_dlsymlist} typedef struct @
3490 @{ @w{const char *@var{name};} @w{void *@var{address};} @} lt_dlsymlist
3491 The @var{name} attribute is a null-terminated character string of the
3492 symbol name, such as @code{"fprintf"}. The @var{address} attribute is a
3493 generic pointer to the appropriate object, such as @code{&fprintf}.
3496 @deftypevar {const lt_dlsymlist } lt_preloaded_symbols[]
3497 An array of @code{lt_dlsymlist} structures, representing all the preloaded
3498 symbols linked into the program proper. For each module
3499 @option{-dlpreopen}ed by the Libtool linked program
3500 there is an element with the @var{name} of the module and an @var{address}
3501 of @code{0}, followed by all symbols exported from this file.
3502 For the executable itself the special name @samp{@@PROGRAM@@} is used.
3503 The last element of all has a @var{name} and @var{address} of
3506 To facilitate inclusion of symbol lists into libraries,
3507 @code{lt_preloaded_symbols} is @samp{#define}d to a suitably unique name
3510 This variable may not be declared @code{const} on some systems due to
3514 Some compilers may allow identifiers that are not valid in ANSI C, such
3515 as dollar signs. Libtool only recognizes valid ANSI C symbols (an
3516 initial ASCII letter or underscore, followed by zero or more ASCII
3517 letters, digits, and underscores), so non-ANSI symbols will not appear
3518 in @code{lt_preloaded_symbols}.
3520 @deftypefun int lt_dlpreload (const lt_dlsymlist *@var{preloaded})
3521 Register the list of preloaded modules @var{preloaded}.
3522 If @var{preloaded} is @code{NULL}, then all previously registered
3523 symbol lists, except the list set by @code{lt_dlpreload_default},
3524 are deleted. Return 0 on success.
3527 @deftypefun int lt_dlpreload_default (const lt_dlsymlist *@var{preloaded})
3528 Set the default list of preloaded modules to @var{preloaded}, which
3529 won't be deleted by @code{lt_dlpreload}. Note that this function does
3530 @emph{not} require libltdl to be initialized using @code{lt_dlinit} and
3531 can be used in the program to register the default preloaded modules.
3532 Instead of calling this function directly, most programs will use the
3533 macro @code{LTDL_SET_PRELOADED_SYMBOLS}.
3535 Return 0 on success.
3538 @defmac LTDL_SET_PRELOADED_SYMBOLS
3539 Set the default list of preloaded symbols.
3540 Should be used in your program to initialize libltdl's
3541 list of preloaded modules.
3548 LTDL_SET_PRELOADED_SYMBOLS();
3554 @deftypefn {Function Type} {int} lt_dlpreload_callback_func (lt_dlhandle @var{handle})
3555 Functions of this type can be passed to @code{lt_dlpreload_open},
3556 which in turn will call back into a function thus passed for each
3557 preloaded module that it opens.
3560 @deftypefun int lt_dlpreload_open (@w{const char *@var{originator},} @w{lt_dlpreload_callback_func *@var{func})}
3561 Load all of the preloaded modules for @var{originator}. For every
3562 module opened in this way, call @var{func}.
3565 To open all of the modules preloaded into @file{libhell.la}
3566 (presumably from within the @file{libhell.a} initialisation code):
3569 #define preloaded_symbols lt_libhell_LTX_preloaded_symbols
3571 static int hell_preload_callback (lt_dlhandle handle);
3577 if (lt_dlpreload (&preloaded_symbols) == 0)
3579 lt_dlpreload_open ("libhell", preload_callback);
3586 Note that to prevent clashes between multiple preloaded modules, the
3587 preloaded symbols are accessed via a mangled symbol name: to get the
3588 symbols preloaded into @samp{libhell}, you must prefix
3589 @samp{preloaded_symbols} with @samp{lt_}; the originator name,
3590 @samp{libhell} in this case; and @samp{_LTX_}. That is,
3591 @samp{lt_libhell_LTX_preloaded_symbols} here.
3595 @node Linking with dlopened modules
3596 @section Linking with dlopened modules
3597 @cindex linking, dlopen
3598 @cindex linking, dlpreopen
3600 When, say, an interpreter application uses dlopened modules to extend
3601 the list of methods it provides, an obvious abstraction for the
3602 maintainers of the interpreter is to have all methods (including the
3603 built in ones supplied with the interpreter) accessed through
3604 dlopen. For one thing, the dlopening functionality will be tested
3605 even during routine invocations. For another, only one subsystem has
3606 to be written for getting methods into the interpreter.
3608 The downside of this abstraction is, of course, that environments that
3609 provide only static linkage can't even load the intrinsic interpreter
3610 methods. Not so! We can statically link those methods by
3611 @strong{dlpreopening} them.
3613 Unfortunately, since platforms such as AIX and cygwin require
3614 that all library symbols must be resolved at compile time, the
3615 interpreter maintainers will need to provide a library to both its own
3616 dlpreopened modules, and third-party modules loaded by dlopen. In
3617 itself, that is not so bad, except that the interpreter too must
3618 provide those same symbols otherwise it will be impossible to resolve
3619 all the symbols required by the modules as they are loaded. Things
3620 are even worse if the code that loads the modules for the interpreter
3621 is itself in a library -- and that is usually the case for any
3622 non-trivial application. Modern platforms take care of this by
3623 automatically loading all of a module's dependency libraries as the
3624 module is loaded (libltdl can do this even on platforms that can't do
3625 it by themselves). In the end, this leads to problems with duplicated
3626 symbols and prevents modules from loading, and prevents the
3627 application from compiling when modules are preloaded.
3630 ,-------------. ,------------------. ,-----------------.
3631 | Interpreter |----> Module------------> Third-party |
3632 `-------------' | Loader | |Dlopened Modules |
3633 | | | `-----------------'
3634 |,-------v--------.| |
3637 |`----------------'| |
3639 |,-------v--------.| ,--------v--------.
3640 ||Module Interface|| |Module Interface |
3641 || Library || | Library |
3642 |`----------------'| `-----------------'
3643 `------------------'
3646 Libtool has the concept of @dfn{weak library interfaces} to circumvent
3647 this problem. Recall that the code that dlopens method-provider
3648 modules for the interpreter application resides in a library: All of
3649 the modules and the dlopener library itself should be linked against
3650 the common library that resolves the module symbols at compile time.
3651 To guard against duplicate symbol definitions, and for dlpreopened
3652 modules to work at all in this scenario, the dlopener library must
3653 declare that it provides a weak library interface to the common
3654 symbols in the library it shares with the modules. That way, when
3655 @command{libtool} links the @strong{Module Loader} library with some
3656 @strong{Dlpreopened Modules} that were in turn linked against the
3657 @strong{Module Interface Library}, it knows that the @strong{Module
3658 Loader} provides an already loaded @strong{Module Interface Library}
3659 to resolve symbols for the @strong{Dlpreopened Modules}, and doesn't
3660 ask the compiler driver to link an identical @strong{Module Interface
3661 Library} dependency library too.
3663 In conjunction with Automake, the @file{Makefile.am} for the
3664 @strong{Module Loader} might look like this:
3667 lib_LTLIBRARIES = libinterface.la libloader.la
3669 libinterface_la_SOURCES = interface.c interface.h
3670 libinterface_la_LDFLAGS = -version-info 3:2:1
3672 libloader_la_SOURCES = loader.c
3673 libloader_la_LDFLAGS = -weak libinterface.la \
3674 -version-info 3:2:1 \
3675 -dlpreopen ../modules/intrinsics.la
3676 libloader_la_LIBADD = $(libinterface_la_OBJECTS)
3679 And the @file{Makefile.am} for the @file{intrinsics.la} module in a
3680 sibling @file{modules} directory might look like this:
3683 AM_CPPFLAGS = -I$(srcdir)/../libloader
3684 AM_LDFLAGS = -no-undefined -module -avoid-version \
3687 noinst_LTLIBRARIES = intrinsics.la
3689 intrinsics_la_LIBADD = ../libloader/libinterface.la
3691 ../libloader/libinterface.la:
3692 cd ../libloader && $(MAKE) $(AM_MAKEFLAGS) libinterface.la
3695 @cindex @option{-weak} option
3696 For a more complex example, see the sources of @file{libltdl} in the
3697 Libtool distribution, which is built with the help of the @option{-weak}
3701 @node Finding the dlname
3702 @section Finding the correct name to dlopen
3703 @cindex names of dynamic modules
3704 @cindex dynamic modules, names
3706 After a library has been linked with @option{-module}, it can be dlopened.
3707 Unfortunately, because of the variation in library names,
3708 your package needs to determine the correct file to dlopen.
3710 The most straightforward and flexible implementation is to determine the
3711 name at runtime, by finding the installed @file{.la} file, and searching
3712 it for the following lines:
3715 # The name that we can @code{dlopen}.
3716 dlname='@var{dlname}'
3719 If @var{dlname} is empty, then the library cannot be dlopened.
3720 Otherwise, it gives the dlname of the library. So, if the library was
3721 installed as @file{/usr/local/lib/libhello.la}, and the @var{dlname} was
3722 @file{libhello.so.3}, then @file{/usr/local/lib/libhello.so.3} should be
3725 If your program uses this approach, then it should search the
3726 directories listed in the @code{LD_LIBRARY_PATH}@footnote{@code{LIBPATH}
3727 on AIX, and @code{SHLIB_PATH} on HP-UX.} environment variable, as well as
3728 the directory where libraries will eventually be installed. Searching
3729 this variable (or equivalent) will guarantee that your program can find
3730 its dlopened modules, even before installation, provided you have linked
3734 @section Unresolved dlopen issues
3735 @cindex pitfalls with dlopen
3736 @cindex dlopening, pitfalls
3737 @cindex trouble with dlopen
3739 The following problems are not solved by using libtool's dlopen support:
3743 Dlopen functions are generally only available on shared library
3744 platforms. If you want your package to be portable to static platforms,
3745 you have to use either libltdl (@pxref{Using libltdl}) or develop your
3746 own alternatives to dlopening dynamic code.
3747 Most reasonable solutions involve writing wrapper functions for the
3748 @code{dlopen} family, which do package-specific tricks when dlopening
3749 is unsupported or not available on a given platform.
3752 There are major differences in implementations of the @code{dlopen}
3753 family of functions. Some platforms do not even use the same function
3754 names (notably HP-UX, with its @code{shl_load} family).
3757 The application developer must write a custom search function in order
3758 to discover the correct module filename to supply to @code{dlopen}.
3762 @chapter Using libltdl
3769 @cindex dynamic linking, applications
3770 @cindex dlopening modules
3771 @cindex modules, dynamic
3772 @cindex application-level dynamic linking
3774 Libtool provides a small library, called @file{libltdl}, that aims at
3775 hiding the various difficulties of dlopening libraries from programmers.
3776 It consists of a few headers and small C source files that can be
3777 distributed with applications that need dlopening functionality. On
3778 some platforms, whose dynamic linkers are too limited for a simple
3779 implementation of @file{libltdl} services, it requires GNU DLD, or it
3780 will only emulate dynamic linking with libtool's dlpreopening mechanism.
3783 libltdl supports currently the following dynamic linking mechanisms:
3787 @code{dlopen} (POSIX compliant systems, GNU/Linux, etc.)
3789 @code{shl_load} (HP-UX)
3791 @code{LoadLibrary} (Win16 and Win32)
3793 @code{load_add_on} (BeOS)
3795 @code{NSAddImage} or @code{NSLinkModule} (Darwin and Mac OS X)
3797 GNU DLD (emulates dynamic linking for static libraries)
3799 libtool's dlpreopen (see @pxref{Dlpreopening})
3803 libltdl is licensed under the terms of the GNU Lesser General
3804 Public License, with the following exception:
3807 As a special exception to the GNU Lesser General Public License,
3808 if you distribute this file as part of a program or library that
3809 is built using GNU Libtool, you may include it under the same
3810 distribution terms that you use for the rest of that program.
3814 * Libltdl interface:: How to use libltdl in your programs.
3815 * Modules for libltdl:: Creating modules that can be @code{dlopen}ed.
3816 * Thread Safety in libltdl:: Registering callbacks for multi-thread safety.
3817 * User defined module data:: Associating data with loaded modules.
3818 * Module loaders for libltdl:: Creating user defined module loaders.
3819 * Distributing libltdl:: How to distribute libltdl with your package.
3822 @node Libltdl interface
3823 @section How to use libltdl in your programs
3826 The libltdl API is similar to the POSIX dlopen interface,
3827 which is very simple but powerful.
3830 To use libltdl in your program you have to include the header file @file{ltdl.h}:
3837 The early releases of libltdl used some symbols that violated the
3838 POSIX namespace conventions. These symbols are now deprecated,
3839 and have been replaced by those described here. If you have code that
3840 relies on the old deprecated symbol names, defining
3841 @samp{LT_NON_POSIX_NAMESPACE} before you include @file{ltdl.h} provides
3842 conversion macros. Whichever set of symbols you use, the new API is
3843 not binary compatible with the last, so you will need to recompile
3844 your application in order to use this version of libltdl.
3847 Note that libltdl is not well tested in a multithreaded environment,
3848 though the intention is that it should work (@pxref{Thread Safety
3849 in libltdl, , Using libltdl in a multi threaded environment}). It was
3850 reported that GNU/Linux's glibc 2.0's @code{dlopen} with
3851 @samp{RTLD_LAZY} (which libltdl uses by default) is not thread-safe,
3852 but this problem is supposed to be fixed in glibc 2.1. On the other
3853 hand, @samp{RTLD_NOW} was reported to introduce problems in
3854 multi-threaded applications on FreeBSD@. Working around these problems
3855 is left as an exercise for the reader; contributions are certainly
3859 The following macros are defined by including @file{ltdl.h}:
3861 @defmac LT_PATHSEP_CHAR
3862 @code{LT_PATHSEP_CHAR} is the system-dependent path separator,
3863 that is, @samp{;} on Windows and @samp{:} everywhere else.
3866 @defmac LT_DIRSEP_CHAR
3867 If @code{LT_DIRSEP_CHAR} is defined, it can be used as directory
3868 separator in addition to @samp{/}. On Windows, this contains
3874 The following types are defined in @file{ltdl.h}:
3876 @deftp {Type} lt_dlhandle
3877 @code{lt_dlhandle} is a module ``handle''.
3878 Every lt_dlopened module has a handle associated with it.
3881 @deftp {Type} lt_dladvise
3882 @code{lt_dladvise} is used to control optional module loading modes.
3883 If it is not used, the default mode of the underlying system module
3887 @deftp {Type} lt_dlsymlist
3888 @code{lt_dlsymlist} is a symbol list for dlpreopened modules.
3889 This structure is described in @pxref{Dlpreopening}.
3894 libltdl provides the following functions:
3896 @deftypefun int lt_dlinit (void)
3898 This function must be called before using libltdl
3899 and may be called several times.
3900 Return 0 on success, otherwise the number of errors.
3903 @deftypefun int lt_dlexit (void)
3904 Shut down libltdl and close all modules.
3905 This function will only then shut down libltdl when it was called as
3906 many times as @code{lt_dlinit} has been successfully called.
3907 Return 0 on success, otherwise the number of errors.
3910 @deftypefun lt_dlhandle lt_dlopen (const char *@var{filename})
3911 Open the module with the file name @var{filename} and return a
3912 handle for it. @code{lt_dlopen} is able to open libtool dynamic
3913 modules, preloaded static modules, the program itself and
3914 native dynamic modules@footnote{Some platforms, notably Mac OS X,
3915 differentiate between a runtime library that cannot be opened by
3916 @code{lt_dlopen} and a dynamic module that can. For maximum
3917 portability you should try to ensure that you only pass
3918 @code{lt_dlopen} objects that have been compiled with libtool's
3919 @option{-module} flag.}.
3921 Unresolved symbols in the module are resolved using its dependency
3922 libraries and previously dlopened modules. If the executable using
3923 this module was linked with the @option{-export-dynamic} flag, then the
3924 global symbols in the executable will also be used to resolve
3925 references in the module.
3927 If @var{filename} is @code{NULL} and the program was linked with
3928 @option{-export-dynamic} or @option{-dlopen self}, @code{lt_dlopen} will
3929 return a handle for the program itself, which can be used to access its
3932 If libltdl cannot find the library and the file name @var{filename} does
3933 not have a directory component it will additionally look in the
3934 following search paths for the module (in the following order):
3937 @item user-defined search path:
3938 This search path can be changed by the program using the
3939 functions @code{lt_dlsetsearchpath}, @code{lt_dladdsearchdir} and
3940 @code{lt_dlinsertsearchdir}.
3942 @item libltdl's search path:
3943 This search path is the value of the environment variable
3944 @env{LTDL_LIBRARY_PATH}.
3946 @item system library search path:
3947 The system dependent library search path
3948 (e.g.@: on GNU/Linux it is @env{LD_LIBRARY_PATH}).
3951 Each search path must be a list of absolute directories separated by
3952 @code{LT_PATHSEP_CHAR}, for example, @code{"/usr/lib/mypkg:/lib/foo"}.
3953 The directory names may not contain the path separator.
3955 If the same module is loaded several times, the same handle is returned.
3956 If @code{lt_dlopen} fails for any reason, it returns @code{NULL}.
3959 @deftypefun lt_dlhandle lt_dlopenext (const char *@var{filename})
3960 The same as @code{lt_dlopen}, except that it tries to append
3961 different file name extensions to the file name.
3962 If the file with the file name @var{filename} cannot be found
3963 libltdl tries to append the following extensions:
3966 @item the libtool archive extension @file{.la}
3967 @item the extension used for native dynamically loadable modules on the host platform, e.g., @file{.so}, @file{.sl}, etc.
3970 This lookup strategy was designed to allow programs that don't
3971 have knowledge about native dynamic libraries naming conventions
3972 to be able to @code{dlopen} such libraries as well as libtool modules
3976 @deftypefun lt_dlhandle lt_dlopenadvise (const char *@var{filename}, @w{lt_dladvise @var{advise}})
3977 The same as @code{lt_dlopen}, except that it also requires an additional
3978 argument which may contain additional hints to the underlying system
3979 module loader. The @var{advise} parameter is opaque and can only be
3980 accessed with the functions documented below.
3982 Note that this function does not change the content of @var{advise}, so
3983 unlike the other calls in this API takes a direct @code{lt_dladvise}
3984 type, and not a pointer to the same.
3987 @deftypefun int lt_dladvise_init (lt_dladvise *@var{advise})
3988 The @var{advise} parameter can be used to pass hints to the module
3989 loader when using @code{lt_dlopenadvise} to perform the loading.
3990 The @var{advise} parameter needs to be initialised by this function
3991 before it can be used. Any memory used by @var{advise} needs to be
3992 recycled with @code{lt_dladvise_destroy} when it is no longer needed.
3994 On failure, @code{lt_dladvise_init} returns non-zero and sets an error
3995 message that can be retrieved with @code{lt_dlerror}.
3998 @deftypefun int lt_dladvise_destroy (lt_dladvise *@var{advise})
3999 Recycle the memory used by @var{advise}. For an example, see the
4000 documentation for @code{lt_dladvise_ext}.
4002 On failure, @code{lt_dladvise_destroy} returns non-zero and sets an error
4003 message that can be retrieved with @code{lt_dlerror}.
4006 @deftypefun int lt_dladvise_ext (lt_dladvise *@var{advise})
4007 Set the @code{ext} hint on @var{advise}. Passing an @var{advise}
4008 parameter to @code{lt_dlopenadvise} with this hint set causes it to
4009 try to append different file name extensions like @code{lt_dlopenext}.
4011 The following example is equivalent to calling
4012 @code{lt_dlopenext (filename)}:
4016 my_dlopenext (const char *filename)
4018 lt_dlhandle handle = 0;
4021 if (!lt_dladvise_init (&advise) && !lt_dladvise_ext (&advise))
4022 handle = lt_dlopenadvise (filename, advise);
4024 lt_dladvise_destroy (&advise);
4030 On failure, @code{lt_dladvise_ext} returns non-zero and sets an error
4031 message that can be retrieved with @code{lt_dlerror}.
4034 @deftypefun int lt_dladvise_global (lt_dladvise *@var{advise})
4035 Set the @code{symglobal} hint on @var{advise}. Passing an @var{advise}
4036 parameter to @code{lt_dlopenadvise} with this hint set causes it to try
4037 to make the loaded module's symbols globally available for resolving
4038 unresolved symbols in subsequently loaded modules.
4040 If neither the @code{symglobal} nor the @code{symlocal} hints are set,
4041 or if a module is loaded without using the @code{lt_dlopenadvise} call
4042 in any case, then the visibility of the module's symbols will be as per
4043 the default for the underlying module loader and OS. Even if a
4044 suitable hint is passed, not all loaders are able to act upon it in
4045 which case @code{lt_dlgetinfo} will reveal whether the hint was actually
4048 On failure, @code{lt_dladvise_global} returns non-zero and sets an error
4049 message that can be retrieved with @code{lt_dlerror}.
4052 @deftypefun int lt_dladvise_local (lt_dladvise *@var{advise})
4053 Set the @code{symlocal} hint on @var{advise}. Passing an @var{advise}
4054 parameter to @code{lt_dlopenadvise} with this hint set causes it to try
4055 to keep the loaded module's symbols hidden so that they are not
4056 visible to subsequently loaded modules.
4058 If neither the @code{symglobal} nor the @code{symlocal} hints are set,
4059 or if a module is loaded without using the @code{lt_dlopenadvise} call
4060 in any case, then the visibility of the module's symbols will be as per
4061 the default for the underlying module loader and OS. Even if a
4062 suitable hint is passed, not all loaders are able to act upon it in
4063 which case @code{lt_dlgetinfo} will reveal whether the hint was actually
4066 On failure, @code{lt_dladvise_local} returns non-zero and sets an error
4067 message that can be retrieved with @code{lt_dlerror}.
4070 @deftypefun int lt_dladvise_resident (lt_dladvise *@var{advise})
4071 Set the @code{resident} hint on @var{advise}. Passing an @var{advise}
4072 parameter to @code{lt_dlopenadvise} with this hint set causes it to try
4073 to make the loaded module resident in memory, so that it cannot be
4074 unloaded with a later call to @code{lt_dlclose}.
4076 On failure, @code{lt_dladvise_resident} returns non-zero and sets an error
4077 message that can be retrieved with @code{lt_dlerror}.
4080 @deftypefun int lt_dladvise_preload (lt_dladvise *@var{advise})
4081 Set the @code{preload} hint on @var{advise}. Passing an @var{advise}
4082 parameter to @code{lt_dlopenadvise} with this hint set causes it to
4083 load only preloaded modules, so that if a suitable preloaded module is
4084 not found, @code{lt_dlopenadvise} will return @code{NULL}.
4087 @deftypefun int lt_dlclose (lt_dlhandle @var{handle})
4088 Decrement the reference count on the module @var{handle}.
4089 If it drops to zero and no other module depends on this module,
4090 then the module is unloaded.
4091 Return 0 on success.
4094 @deftypefun {void *} lt_dlsym (lt_dlhandle @var{handle}, const char *@var{name})
4095 Return the address in the module @var{handle}, where the symbol given
4096 by the null-terminated string @var{name} is loaded.
4097 If the symbol cannot be found, @code{NULL} is returned.
4100 @deftypefun {const char *} lt_dlerror (void)
4101 Return a human readable string describing the most
4102 recent error that occurred from any of libltdl's functions.
4103 Return @code{NULL} if no errors have occurred since initialization
4104 or since it was last called.
4107 @deftypefun int lt_dladdsearchdir (const char *@var{search_dir})
4108 Append the search directory @var{search_dir} to the current user-defined
4109 library search path. Return 0 on success.
4112 @deftypefun int lt_dlinsertsearchdir (@w{const char *@var{before}}, @w{const char *@var{search_dir}})
4113 Insert the search directory @var{search_dir} into the user-defined library
4114 search path, immediately before the element starting at address
4115 @var{before}. If @var{before} is @samp{NULL}, then @var{search_dir} is
4116 appending as if @code{lt_dladdsearchdir} had been called. Return 0 on success.
4119 @deftypefun int lt_dlsetsearchpath (const char *@var{search_path})
4120 Replace the current user-defined library search path with
4121 @var{search_path}, which must be a list of absolute directories separated
4122 by @code{LT_PATHSEP_CHAR}. Return 0 on success.
4125 @deftypefun {const char *} lt_dlgetsearchpath (void)
4126 Return the current user-defined library search path.
4129 @deftypefun int lt_dlforeachfile (@w{const char *@var{search_path}}, @w{int (*@var{func}) (const char *@var{filename}, void * @var{data})}, @w{void * @var{data}})
4130 In some applications you may not want to load individual modules with
4131 known names, but rather find all of the modules in a set of
4132 directories and load them all during initialisation. With this function
4133 you can have libltdl scan the @code{LT_PATHSEP_CHAR}-delimited directory list
4134 in @var{search_path} for candidates, and pass them, along with
4135 @var{data} to your own callback function, @var{func}. If @var{search_path} is
4136 @samp{NULL}, then search all of the standard locations that
4137 @code{lt_dlopen} would examine. This function will continue to make
4138 calls to @var{func} for each file that it discovers in @var{search_path}
4139 until one of these calls returns non-zero, or until the files are
4140 exhausted. @samp{lt_dlforeachfile} returns the value returned by the last
4141 call made to @var{func}.
4143 For example you could define @var{func} to build an ordered
4144 @dfn{argv}-like vector of files using @var{data} to hold the address of
4145 the start of the vector.
4148 @deftypefun int lt_dlmakeresident (lt_dlhandle @var{handle})
4149 Mark a module so that it cannot be @samp{lt_dlclose}d. This can be
4150 useful if a module implements some core functionality in your project
4151 that would cause your code to crash if removed. Return 0 on success.
4153 If you use @samp{lt_dlopen (NULL)} to get a @var{handle} for the running
4154 binary, that handle will always be marked as resident, and consequently
4155 cannot be successfully @samp{lt_dlclose}d.
4158 @deftypefun int lt_dlisresident (lt_dlhandle @var{handle})
4159 Check whether a particular module has been marked as resident, returning 1
4160 if it has or 0 otherwise. If there is an error while executing this
4161 function, return -1 and set an error message for retrieval with
4165 @node Modules for libltdl
4166 @section Creating modules that can be @code{dlopen}ed
4168 Libtool modules are created like normal libtool libraries with a few
4171 You have to link the module with libtool's @option{-module} switch,
4172 and you should link any program that is intended to dlopen the module with
4173 @option{-dlopen @var{modulename.la}} where possible, so that libtool can
4174 dlpreopen the module on platforms that do not support dlopening. If
4175 the module depends on any other libraries, make sure you specify them
4176 either when you link the module or when you link programs that dlopen it.
4177 If you want to disable versioning (@pxref{Versioning}) for a specific module
4178 you should link it with the @option{-avoid-version} switch.
4179 Note that libtool modules don't need to have a "lib" prefix.
4180 However, Automake 1.4 or higher is required to build such modules.
4182 Usually a set of modules provide the same interface, i.e.@: exports the same
4183 symbols, so that a program can dlopen them without having to know more
4184 about their internals: In order to avoid symbol conflicts all exported
4185 symbols must be prefixed with "modulename_LTX_" (@var{modulename} is
4186 the name of the module). Internal symbols must be named in such a way
4187 that they won't conflict with other modules, for example, by prefixing
4188 them with "_modulename_". Although some platforms support having the
4189 same symbols defined more than once it is generally not portable and
4190 it makes it impossible to dlpreopen such modules.
4192 libltdl will automatically cut the prefix off to get the real name of
4193 the symbol. Additionally, it supports modules that do not use a
4194 prefix so that you can also dlopen non-libtool modules.
4196 @file{foo1.c} gives an example of a portable libtool module.
4197 Exported symbols are prefixed with "foo1_LTX_", internal symbols
4198 with "_foo1_". Aliases are defined at the beginning so that the code
4202 /* aliases for the exported symbols */
4203 #define foo foo1_LTX_foo
4204 #define bar foo1_LTX_bar
4206 /* a global variable definition */
4209 /* a private function */
4210 int _foo1_helper() @{
4214 /* an exported function */
4216 return _foo1_helper();
4221 The @file{Makefile.am} contains the necessary rules to build the
4222 module @file{foo1.la}:
4226 lib_LTLIBRARIES = foo1.la
4228 foo1_la_SOURCES = foo1.c
4229 foo1_la_LDFLAGS = -module
4234 @node Thread Safety in libltdl
4235 @section Using libltdl in a multi threaded environment
4237 Libltdl provides a wrapper around whatever dynamic run-time object
4238 loading mechanisms are provided by the host system, many of which are
4239 themselves not thread safe. Consequently libltdl cannot itself be
4240 consistently thread safe.
4242 If you wish to use libltdl in a multithreaded environment, then you
4243 must mutex lock around libltdl calls, since they may in turn be calling
4244 non-thread-safe system calls on some target hosts.
4246 Some old releases of libtool provided a mutex locking API that
4247 was unusable with POSIX threads, so callers were forced to lock around
4248 all libltdl API calls anyway. That mutex locking API was
4249 next to useless, and is not present in current releases.
4251 Some future release of libtool may provide a new POSIX thread
4252 compliant mutex locking API.
4254 @node User defined module data
4255 @section Data associated with loaded modules
4257 Some of the internal information about each loaded module that is
4258 maintained by libltdl is available to the user, in the form of this
4261 @deftypefn {Type} {struct} lt_dlinfo @{ @w{char *@var{filename};} @
4262 @w{char *@var{name};} @w{int @var{ref_count};} @
4263 @w{int @var{is_resident};} @w{int @var{is_symglobal};} @
4264 @w{int @var{is_symlocal};}@}
4265 @code{lt_dlinfo} is used to store information about a module.
4266 The @var{filename} attribute is a null-terminated character string of
4267 the real module file name. If the module is a libtool module then
4268 @var{name} is its module name (e.g.@: @code{"libfoo"} for
4269 @code{"dir/libfoo.la"}), otherwise it is set to @code{NULL}. The
4270 @var{ref_count} attribute is a reference counter that describes how
4271 often the same module is currently loaded. The remaining fields can
4272 be compared to any hints that were passed to @code{lt_dlopenadvise}
4273 to determine whether the underlying loader was able to follow them.
4276 The following function will return a pointer to libltdl's internal copy
4277 of this structure for the given @var{handle}:
4279 @deftypefun {const lt_dlinfo *} lt_dlgetinfo (@w{lt_dlhandle @var{handle}})
4280 Return a pointer to a struct that contains some information about
4281 the module @var{handle}. The contents of the struct must not be modified.
4282 Return @code{NULL} on failure.
4285 Furthermore, in order to save you from having to keep a list of the
4286 handles of all the modules you have loaded, these functions allow you to
4287 iterate over libltdl's list of loaded modules:
4289 @deftp {Type} lt_dlinterface_id
4290 The opaque type used to hold the module interface details for each
4291 registered libltdl client.
4294 @deftypefn {Type} int lt_dlhandle_interface (@w{lt_dlhandle @var{handle},} @
4295 @w{const char *@var{id_string}})
4296 Functions of this type are called to check that a handle conforms to a
4297 library's expected module interface when iterating over the global
4298 handle list. You should be careful to write a callback function of
4299 this type that can correctly identify modules that belong to this
4300 client, both to prevent other clients from accidentally finding your
4301 loaded modules with the iterator functions below, and vice versa. The
4302 best way to do this is to check that module @var{handle} conforms
4303 to the interface specification of your loader using @code{lt_dlsym}.
4305 The callback may be given @strong{every} module loaded by all the
4306 libltdl module clients in the current address space, including any
4307 modules loaded by other libraries such as libltdl itself, and should
4308 return non-zero if that module does not fulfill the interface
4309 requirements of your loader.
4313 my_interface_cb (lt_dlhandle handle, const char *id_string)
4315 char *(*module_id) (void) = NULL;
4317 /* @r{A valid my_module must provide all of these symbols.} */
4318 if (!((module_id = (char*(*)(void)) lt_dlsym ("module_version"))
4319 && lt_dlsym ("my_module_entrypoint")))
4322 if (strcmp (id_string, module_id()) != 0)
4330 @deftypefun lt_dlinterface_id lt_dlinterface_register @
4331 (@w{const char *@var{id_string}}, @w{lt_dlhandle_interface *@var{iface}})
4332 Use this function to register your interface validator with libltdl,
4333 and in return obtain a unique key to store and retrieve per-module data.
4334 You supply an @var{id_string} and @var{iface} so that the resulting
4335 @code{lt_dlinterface_id} can be used to filter the module handles
4336 returned by the iteration functions below. If @var{iface} is @code{NULL},
4337 all modules will be matched.
4340 @deftypefun void lt_dlinterface_free (@w{lt_dlinterface_id @var{iface}})
4341 Release the data associated with @var{iface}.
4344 @deftypefun int lt_dlhandle_map (@w{lt_dlinterface_id @var{iface}}, @
4345 @w{int (*@var{func}) (lt_dlhandle @var{handle}, void * @var{data})}, @
4346 @w{void * @var{data}})
4347 For each module that matches @var{iface}, call the function
4348 @var{func}. When writing the @var{func} callback function, the
4349 argument @var{handle} is the handle of a loaded module, and
4350 @var{data} is the last argument passed to @code{lt_dlhandle_map}. As
4351 soon as @var{func} returns a non-zero value for one of the handles,
4352 @code{lt_dlhandle_map} will stop calling @var{func} and immediately
4353 return that non-zero value. Otherwise 0 is eventually returned when
4354 @var{func} has been successfully called for all matching modules.
4357 @deftypefun lt_dlhandle lt_dlhandle_iterate (@w{lt_dlinterface_id @
4358 @var{iface}}, @w{lt_dlhandle @var{place}})
4359 Iterate over the module handles loaded by @var{iface}, returning the
4360 first matching handle in the list if @var{place} is @code{NULL}, and
4361 the next one on subsequent calls. If @var{place} is the last element
4362 in the list of eligible modules, this function returns @code{NULL}.
4365 lt_dlhandle handle = 0;
4366 lt_dlinterface_id iface = my_interface_id;
4368 while ((handle = lt_dlhandle_iterate (iface, handle)))
4375 @deftypefun lt_dlhandle lt_dlhandle_fetch (@w{lt_dlinterface_id @var{iface}}, @w{const char *@var{module_name}})
4376 Search through the module handles loaded by @var{iface} for a module named
4377 @var{module_name}, returning its handle if found or else @code{NULL}
4378 if no such named module has been loaded by @var{iface}.
4381 However, you might still need to maintain your own list of loaded
4382 module handles (in parallel with the list maintained inside libltdl)
4383 if there were any other data that your application wanted to associate
4384 with each open module. Instead, you can use the following API
4385 calls to do that for you. You must first obtain a unique interface id
4386 from libltdl as described above, and subsequently always use it to
4387 retrieve the data you stored earlier. This allows different libraries
4388 to each store their own data against loaded modules, without
4389 interfering with one another.
4391 @deftypefun {void *} lt_dlcaller_set_data (@w{lt_dlinterface_id @var{key}}, @w{lt_dlhandle @var{handle}}, @w{void * @var{data}})
4392 Set @var{data} as the set of data uniquely associated with @var{key} and
4393 @var{handle} for later retrieval. This function returns the @var{data}
4394 previously associated with @var{key} and @var{handle} if any. A result of
4395 0, may indicate that a diagnostic for the last error (if any) is available
4396 from @code{lt_dlerror()}.
4398 For example, to correctly remove some associated data:
4401 void *stale = lt_dlcaller_set_data (key, handle, 0);
4408 char *error_msg = lt_dlerror ();
4410 if (error_msg != NULL)
4412 my_error_handler (error_msg);
4413 return STATUS_FAILED;
4419 @deftypefun {void *} lt_dlcaller_get_data (@w{lt_dlinterface_id @var{key}}, @w{lt_dlhandle @var{handle}})
4420 Return the address of the data associated with @var{key} and
4421 @var{handle}, or else @code{NULL} if there is none.
4424 Old versions of libltdl also provided a simpler, but similar, API
4425 based around @code{lt_dlcaller_id}. Unfortunately, it had no
4426 provision for detecting whether a module belonged to a particular
4427 interface as libltdl didn't support multiple loaders in the same
4428 address space at that time. Those APIs are no longer supported
4429 as there would be no way to stop clients of the old APIs from
4430 seeing (and accidentally altering) modules loaded by other libraries.
4433 @node Module loaders for libltdl
4434 @section How to create and register new module loaders
4436 Sometimes libltdl's many ways of gaining access to modules are not
4437 sufficient for the purposes of a project. You can write your own
4438 loader, and register it with libltdl so that @code{lt_dlopen} will be
4441 Writing a loader involves writing at least three functions that can be
4442 called by @code{lt_dlopen}, @code{lt_dlsym} and @code{lt_dlclose}.
4443 Optionally, you can provide a finalisation function to perform any
4444 cleanup operations when @code{lt_dlexit} executes, and a symbol prefix
4445 string that will be prepended to any symbols passed to @code{lt_dlsym}.
4446 These functions must match the function pointer types below, after
4447 which they can be allocated to an instance of @code{lt_user_dlloader}
4450 Registering the loader requires that you choose a name for it, so that it
4451 can be recognised by @code{lt_dlloader_find} and removed with
4452 @code{lt_dlloader_remove}. The name you choose must be unique, and not
4453 already in use by libltdl's builtin loaders:
4457 The system dynamic library loader, if one exists.
4459 The GNU dld loader, if @file{libdld} was installed when libltdl was
4462 The loader for @code{lt_dlopen}ing of preloaded static modules.
4465 The prefix "dl" is reserved for loaders supplied with future versions of
4466 libltdl, so you should not use that for your own loader names.
4469 The following types are defined in @file{ltdl.h}:
4471 @deftp {Type} lt_module
4472 @code{lt_module} is a dlloader dependent module.
4473 The dynamic module loader extensions communicate using these low
4477 @deftp {Type} lt_dlloader
4478 @code{lt_dlloader} is a handle for module loader types.
4481 @deftp {Type} lt_user_data
4482 @code{lt_user_data} is used for specifying loader instance data.
4485 @deftypefn {Type} {struct} lt_user_dlloader @{@w{const char *@var{sym_prefix};} @w{lt_module_open *@var{module_open};} @w{lt_module_close *@var{module_close};} @w{lt_find_sym *@var{find_sym};} @w{lt_dlloader_exit *@var{dlloader_exit};} @}
4486 If you want to define a new way to open dynamic modules, and have the
4487 @code{lt_dlopen} API use it, you need to instantiate one of these
4488 structures and pass it to @code{lt_dlloader_add}. You can pass whatever
4489 you like in the @var{dlloader_data} field, and it will be passed back as
4490 the value of the first parameter to each of the functions specified in
4491 the function pointer fields.
4494 @deftypefn {Type} lt_module lt_module_open (@w{const char *@var{filename}})
4495 The type of the loader function for an @code{lt_dlloader} module
4496 loader. The value set in the dlloader_data field of the @code{struct
4497 lt_user_dlloader} structure will be passed into this function in the
4498 @var{loader_data} parameter. Implementation of such a function should
4499 attempt to load the named module, and return an @code{lt_module}
4500 suitable for passing in to the associated @code{lt_module_close} and
4501 @code{lt_sym_find} function pointers. If the function fails it should
4502 return @code{NULL}, and set the error message with @code{lt_dlseterror}.
4505 @deftypefn {Type} int lt_module_close (@w{lt_user_data @var{loader_data},} @w{lt_module @var{module}})
4506 The type of the unloader function for a user defined module loader.
4507 Implementation of such a function should attempt to release
4508 any resources tied up by the @var{module} module, and then unload it
4509 from memory. If the function fails for some reason, set the error
4510 message with @code{lt_dlseterror} and return non-zero.
4513 @deftypefn {Type} {void *} lt_find_sym (@w{lt_module @var{module},} @w{const char *@var{symbol}})
4514 The type of the symbol lookup function for a user defined module loader.
4515 Implementation of such a function should return the address of the named
4516 @var{symbol} in the module @var{module}, or else set the error message
4517 with @code{lt_dlseterror} and return @code{NULL} if lookup fails.
4520 @deftypefn {Type} int lt_dlloader_exit (@w{lt_user_data @var{loader_data}})
4521 The type of the finalisation function for a user defined module loader.
4522 Implementation of such a function should free any resources associated
4523 with the loader, including any user specified data in the
4524 @code{dlloader_data} field of the @code{lt_user_dlloader}. If non-@code{NULL},
4525 the function will be called by @code{lt_dlexit}, and
4526 @code{lt_dlloader_remove}.
4533 register_myloader (void)
4535 lt_user_dlloader dlloader;
4537 /* User modules are responsible for their own initialisation. */
4538 if (myloader_init () != 0)
4539 return MYLOADER_INIT_ERROR;
4541 dlloader.sym_prefix = NULL;
4542 dlloader.module_open = myloader_open;
4543 dlloader.module_close = myloader_close;
4544 dlloader.find_sym = myloader_find_sym;
4545 dlloader.dlloader_exit = myloader_exit;
4546 dlloader.dlloader_data = (lt_user_data)myloader_function;
4548 /* Add my loader as the default module loader. */
4549 if (lt_dlloader_add (lt_dlloader_next (NULL), &dlloader,
4557 Note that if there is any initialisation required for the loader,
4558 it must be performed manually before the loader is registered --
4559 libltdl doesn't handle user loader initialisation.
4561 Finalisation @emph{is} handled by libltdl however, and it is important
4562 to ensure the @code{dlloader_exit} callback releases any resources claimed
4563 during the initialisation phase.
4567 libltdl provides the following functions for writing your own module
4570 @deftypefun int lt_dlloader_add (@w{lt_dlloader *@var{place},} @
4571 @w{lt_user_dlloader *@var{dlloader},} @w{const char *@var{loader_name}})
4572 Add a new module loader to the list of all loaders, either as the
4573 last loader (if @var{place} is @code{NULL}), else immediately before the
4574 loader passed as @var{place}. @var{loader_name} will be returned by
4575 @code{lt_dlloader_name} if it is subsequently passed a newly
4576 registered loader. These @var{loader_name}s must be unique, or
4577 @code{lt_dlloader_remove} and @code{lt_dlloader_find} cannot
4578 work. Returns 0 for success.
4581 /* Make myloader be the last one. */
4582 if (lt_dlloader_add (NULL, myloader) != 0)
4583 perror (lt_dlerror ());
4587 @deftypefun int lt_dlloader_remove (@w{const char *@var{loader_name}})
4588 Remove the loader identified by the unique name, @var{loader_name}.
4589 Before this can succeed, all modules opened by the named loader must
4590 have been closed. Returns 0 for success, otherwise an error message can
4591 be obtained from @code{lt_dlerror}.
4594 /* Remove myloader. */
4595 if (lt_dlloader_remove ("myloader") != 0)
4596 perror (lt_dlerror ());
4600 @deftypefun {lt_dlloader *} lt_dlloader_next (@w{lt_dlloader *@var{place}})
4601 Iterate over the module loaders, returning the first loader if @var{place} is
4602 @code{NULL}, and the next one on subsequent calls. The handle is for use with
4603 @code{lt_dlloader_add}.
4606 /* Make myloader be the first one. */
4607 if (lt_dlloader_add (lt_dlloader_next (NULL), myloader) != 0)
4612 @deftypefun {lt_dlloader *} lt_dlloader_find (@w{const char *@var{loader_name}})
4613 Return the first loader with a matching @var{loader_name} identifier, or else
4614 @code{NULL}, if the identifier is not found.
4616 The identifiers that may be used by libltdl itself, if the host
4617 architecture supports them are @dfn{dlopen}@footnote{This is used for
4618 the host dependent module loading API -- @code{shl_load} and
4619 @code{LoadLibrary} for example}, @dfn{dld} and @dfn{dlpreload}.
4622 /* Add a user loader as the next module loader to be tried if
4623 the standard dlopen loader were to fail when lt_dlopening. */
4624 if (lt_dlloader_add (lt_dlloader_find ("dlopen"), myloader) != 0)
4629 @deftypefun {const char *} lt_dlloader_name (@w{lt_dlloader *@var{place}})
4630 Return the identifying name of @var{place}, as obtained from
4631 @code{lt_dlloader_next} or @code{lt_dlloader_find}. If this function fails,
4632 it will return @code{NULL} and set an error for retrieval with
4636 @deftypefun {lt_user_data *} lt_dlloader_data (@w{lt_dlloader *@var{place}})
4637 Return the address of the @code{dlloader_data} of @var{place}, as
4638 obtained from @code{lt_dlloader_next} or @code{lt_dlloader_find}. If
4639 this function fails, it will return @code{NULL} and set an error for
4640 retrieval with @code{lt_dlerror}.
4643 @subsection Error handling within user module loaders
4645 @deftypefun int lt_dladderror (@w{const char *@var{diagnostic}})
4646 This function allows you to integrate your own error messages into
4647 @code{lt_dlerror}. Pass in a suitable diagnostic message for return by
4648 @code{lt_dlerror}, and an error identifier for use with
4649 @code{lt_dlseterror} is returned.
4651 If the allocation of an identifier fails, this function returns -1.
4654 int myerror = lt_dladderror ("Doh!");
4656 perror (lt_dlerror ());
4660 @deftypefun int lt_dlseterror (@w{int @var{errorcode}})
4661 When writing your own module loaders, you should use this function to
4662 raise errors so that they are propagated through the @code{lt_dlerror}
4663 interface. All of the standard errors used by libltdl are declared in
4664 @file{ltdl.h}, or you can add more of your own with
4665 @code{lt_dladderror}. This function returns 0 on success.
4668 if (lt_dlseterror (LTDL_ERROR_NO_MEMORY) != 0)
4669 perror (lt_dlerror ());
4673 @node Distributing libltdl
4674 @section How to distribute libltdl with your package
4676 Even though libltdl is installed together with libtool, you may wish
4677 to include libltdl in the distribution of your package, for the
4678 convenience of users of your package that don't have libtool or
4679 libltdl installed, or if you are using features of a very new version
4680 of libltdl that you don't expect your users to have yet. In such
4681 cases, you must decide which flavor of libltdl you want to use: a
4682 convenience library or an installable libtool library.
4684 The most simplistic way to add @code{libltdl} to your package is to
4685 copy all the @file{libltdl} source files to a subdirectory within
4686 your package and to build and link them along with the rest of your
4687 sources. To help you do this, the m4 macros for Autoconf are
4688 available in @file{ltdl.m4}. You must ensure that they are available
4689 in @file{aclocal.m4} before you run Autoconf@footnote{@c
4691 We used to recommend adding the contents of @file{ltdl.m4} to
4692 @file{acinclude.m4}, but with @command{aclocal} from a modern
4693 Automake (1.8 or newer) and this release of libltdl that is not only
4694 unnecessary but makes it easy to forget to upgrade @file{acinclude.m4}
4695 if you move to a different release of libltdl.
4697 }. Having made the macros available, you must add a call to the
4698 @samp{LTDL_INIT} macro (after the call to @samp{LT_INIT})
4699 to your package's @file{configure.ac} to
4700 perform the configure time checks required to build the library
4701 correctly. Unfortunately, this method has problems if you then try to
4702 link the package binaries with an installed libltdl, or a library that
4703 depends on libltdl, because of the duplicate symbol definitions. For
4704 example, ultimately linking against two different versions of libltdl,
4705 or against both a local convenience library and an installed libltdl
4706 is bad. Ensuring that only one copy of the libltdl sources are linked
4707 into any program is left as an exercise for the reader.
4709 @defmac LT_CONFIG_LTDL_DIR (@var{directory})
4710 Declare @var{directory} to be the location of the @code{libltdl}
4711 source files, for @command{libtoolize --ltdl} to place
4712 them. @xref{Invoking libtoolize}, for more details. Provided that you
4713 add an appropriate @code{LT_CONFIG_LTDL_DIR} call in your
4714 @file{configure.ac} before calling @command{libtoolize}, the
4715 appropriate @code{libltdl} files will be installed automatically.
4718 @defmac LTDL_INIT (@var{options})
4719 @defmacx LT_WITH_LTDL
4720 @defmacx AC_WITH_LTDL
4721 @code{AC_WITH_LTDL} and @code{LT_WITH_LTDL} are deprecated names for
4722 older versions of this macro; @command{autoupdate} will update your
4723 @file{configure.ac} file.
4725 This macro adds the following options to the @command{configure}
4729 @item --with-ltdl-include @var{installed-ltdl-header-dir}
4730 The @code{LTDL_INIT} macro will look in the standard header file
4731 locations to find the installed @code{libltdl} headers. If
4732 @code{LTDL_INIT} can't find them by itself, the person who builds
4733 your package can use this option to tell @command{configure} where
4734 the installed @code{libltdl} headers are.
4736 @item --with-ltdl-lib @var{installed-ltdl-library-dir}
4737 Similarly, the person building your package can use this option to
4738 help @command{configure} find the installed @file{libltdl.la}.
4740 @item --with-included-ltdl
4741 If there is no installed @code{libltdl}, or in any case if the
4742 person building your package would rather use the @code{libltdl}
4743 sources shipped with the package in the subdirectory named by
4744 @code{LT_CONFIG_LTDL_DIR}, they should pass this option to
4745 @command{configure}.
4748 If the @option{--with-included-ltdl} is not passed at
4749 configure time, and an installed @code{libltdl} is not
4752 Even if libltdl is installed, @samp{LTDL_INIT} may fail
4753 to detect it if libltdl depends on symbols provided by libraries
4754 other than the C library.
4756 }, then @command{configure} will exit immediately with an error that
4757 asks the user to either specify the location of an installed
4758 @code{libltdl} using the @option{--with-ltdl-include} and
4759 @option{--with-ltdl-lib} options, or to build with the
4760 @code{libltdl} sources shipped with the package by passing
4761 @option{--with-included-ltdl}.
4763 If an installed @code{libltdl} is found, then @code{LIBLTDL} is set to
4764 the link flags needed to use it, and @code{LTDLINCL} to the preprocessor
4765 flags needed to find the installed headers, and @code{LTDLDEPS} will
4766 be empty. Note, however, that no version checking is performed. You
4767 should manually check for the @code{libltdl} features you need in
4768 @file{configure.ac}:
4774 # The lt_dladvise_init symbol was added with libtool-2.2
4775 if test "x$with_included_ltdl" != "xyes"; then
4776 save_CFLAGS="$CFLAGS"
4777 save_LDFLAGS="$LDFLAGS"
4778 CFLAGS="$CFLAGS $LTDLINCL"
4779 LDFLAGS="$LDFLAGS $LIBLTDL"
4780 AC_CHECK_LIB([ltdl], [lt_dladvise_init],
4782 [AC_MSG_ERROR([installed libltdl is too old])])
4783 LDFLAGS="$save_LDFLAGS"
4784 CFLAGS="$save_CFLAGS"
4788 @var{options} may include no more than one of the following build
4789 modes depending on how you want your project to build @code{libltdl}:
4790 @samp{nonrecursive}, @samp{recursive}, or @samp{subproject}. In order
4791 for @command{libtoolize} to detect this option correctly, if you
4792 supply one of these arguments, they must be given literally (i.e.,
4793 macros or shell variables that expand to the correct ltdl mode will not
4798 This is how the Libtool project distribution builds the @code{libltdl}
4799 we ship and install. If you wish to use Automake to build
4800 @code{libltdl} without invoking a recursive make to descend into the
4801 @code{libltdl} subdirectory, then use this option. You will need to set
4802 your configuration up carefully to make this work properly, and you will
4803 need releases of Autoconf and Automake that support
4804 @code{subdir-objects} and @code{LIBOBJDIR} properly. In your
4805 @file{configure.ac}, add:
4808 AM_INIT_AUTOMAKE([subdir-objects])
4809 AC_CONFIG_HEADERS([config.h])
4810 LT_CONFIG_LTDL_DIR([libltdl])
4812 LTDL_INIT([nonrecursive])
4816 You @emph{have to} use a config header, but it may have a name different
4817 than @file{config.h}.
4819 Also, add the following near the top of your @file{Makefile.am}:
4831 noinst_LTLIBRARIES =
4835 include libltdl/Makefile.inc
4839 Unless you build no other libraries from this @file{Makefile.am},
4840 you will also need to change @code{lib_LTLIBRARIES} to assign with
4841 @samp{+=} so that the @code{libltdl} targets declared in
4842 @file{Makefile.inc} are not overwritten.
4845 This build mode still requires that you use Automake, but (in contrast
4846 with @samp{nonrecursive}) uses the more usual device of starting another
4847 @code{make} process in the @file{libltdl} subdirectory. To use this
4848 mode, you should add to your @file{configure.ac}:
4852 AC_CONFIG_HEADERS([config.h])
4853 LT_CONFIG_LTDL_DIR([libltdl])
4855 LTDL_INIT([recursive])
4856 AC_CONFIG_FILES([libltdl/Makefile])
4860 Again, you @emph{have to} use a config header, but it may have a name
4861 different than @file{config.h} if you like.
4863 Also, add this to your @file{Makefile.am}:
4870 This mode is the default unless you explicitly add @code{recursive} or
4871 @code{nonrecursive} to your @code{LTDL_INIT} options; @code{subproject}
4872 is the only mode supported by previous releases of libltdl. Even if you
4873 do not use Autoconf in the parent project, then, in @samp{subproject}
4874 mode, still @code{libltdl} contains all the necessary files to configure
4875 and build itself -- you just need to arrange for your build system to
4876 call @file{libltdl/configure} with appropriate options, and then run
4877 @code{make} in the @code{libltdl} subdirectory.
4879 If you @emph{are} using Autoconf and Automake, then you will need to add
4880 the following to your @file{configure.ac}:
4883 LT_CONFIG_LTDL_DIR([libltdl])
4888 and to @file{Makefile.am}:
4895 Aside from setting the libltdl build mode, there are other keywords
4896 that you can pass to @code{LTDL_INIT} to modify its behavior when
4897 @option{--with-included-ltdl} has been given:
4901 This is the default unless you explicitly add @code{installable} to
4902 your @code{LTDL_INIT} options.
4904 This keyword will cause options to be passed to the @command{configure}
4905 script in the subdirectory named by @code{LT_CONFIG_LTDL_DIR} in order
4906 to cause it to be built as a convenience library. If you're not
4907 using automake, you will need to define @code{top_build_prefix},
4908 @code{top_builddir}, and @code{top_srcdir} in your makefile so that
4909 @code{LIBLTDL}, @code{LTDLDEPS}, and @code{LTDLINCL} expand correctly.
4911 One advantage of the convenience library is that it is not installed,
4912 so the fact that you use @code{libltdl} will not be apparent to the
4913 user, and it won't overwrite a pre-installed version of
4914 @code{libltdl} the system might already have in the installation
4915 directory. On the other hand, if you want to upgrade @code{libltdl}
4916 for any reason (e.g.@: a bugfix) you'll have to recompile your package
4917 instead of just replacing the shared installed version of
4918 @code{libltdl}. However, if your programs or libraries are linked
4919 with other libraries that use such a pre-installed version of
4920 @code{libltdl}, you may get linker errors or run-time crashes.
4921 Another problem is that you cannot link the convenience library into
4922 more than one libtool library, then link a single program with those
4923 libraries, because you may get duplicate symbols. In general you can
4924 safely use the convenience library in programs that don't depend on
4925 other libraries that might use @code{libltdl} too.
4928 This keyword will pass options to the @command{configure}
4929 script in the subdirectory named by @code{LT_CONFIG_LTDL_DIR} in order
4930 to cause it to be built as an installable library. If you're not
4931 using automake, you will need to define @code{top_build_prefix},
4932 @code{top_builddir} and @code{top_srcdir} in your makefile so that
4933 @code{LIBLTDL}, @code{LTDLDEPS}, and @code{LTDLINCL} are expanded
4936 Be aware that you could overwrite another @code{libltdl} already
4937 installed to the same directory if you use this option.
4941 Whatever method you use, @samp{LTDL_INIT} will define the shell variable
4942 @code{LIBLTDL} to the link flag that you should use to link with
4943 @code{libltdl}, the shell variable @code{LTDLDEPS} to the files that
4944 can be used as a dependency in @file{Makefile} rules, and the shell
4945 variable @code{LTDLINCL} to the preprocessor flag that you should use to
4946 compile programs that include @file{ltdl.h}. So, when you want to link a
4947 program with libltdl, be it a convenience, installed or installable
4948 library, just use @samp{$(LTDLINCL)} for preprocessing and compilation,
4949 and @samp{$(LIBLTDL)} for linking.
4953 If your package is built using an installed version of @code{libltdl},
4954 @code{LIBLTDL} will be set to the compiler flags needed to link against
4955 the installed library, @code{LTDLDEPS} will be empty, and @code{LTDLINCL}
4956 will be set to the compiler flags needed to find the @code{libltdl}
4960 If your package is built using the convenience libltdl, @code{LIBLTDL}
4961 and @code{LTDLDEPS} will be the pathname for the convenience version of
4962 libltdl (starting with @samp{$@{top_builddir@}/} or
4963 @samp{$@{top_build_prefix@}}) and @code{LTDLINCL} will be @option{-I}
4964 followed by the directory that contains @file{ltdl.h} (starting with
4965 @samp{$@{top_srcdir@}/}).
4968 If an installable version of the included @code{libltdl} is being
4969 built, its pathname starting with @samp{$@{top_builddir@}/} or
4970 @samp{$@{top_build_prefix@}}, will be stored in @code{LIBLTDL} and
4971 @code{LTDLDEPS}, and @code{LTDLINCL} will be set just like in the case of
4972 convenience library.
4975 You should probably also use the @samp{dlopen} option to @code{LT_INIT}
4976 in your @file{configure.ac}, otherwise libtool will assume no dlopening
4977 mechanism is supported, and revert to dlpreopening, which is probably not
4978 what you want. Avoid using the @option{-static},
4979 @option{-static-libtool-libs}, or @option{-all-static}
4980 switches when linking programs with libltdl. This will not work on
4981 all platforms, because the dlopening functions may not be available
4984 The following example shows you how to embed an installable libltdl in
4985 your package. In order to use the convenience variant, just replace the
4986 @code{LTDL_INIT} option @samp{installable} with @samp{convenience}. We
4987 assume that libltdl was embedded using @samp{libtoolize --ltdl}.
4992 # Name the subdirectory that contains libltdl sources
4993 LT_CONFIG_LTDL_DIR([libltdl])
4995 # Configure libtool with dlopen support if possible
4998 # Enable building of the installable libltdl library
4999 LTDL_INIT([installable])
5008 AM_CPPFLAGS = $(LTDLINCL)
5010 myprog_LDFLAGS = -export-dynamic
5011 myprog_LDADD = $(LIBLTDL) -dlopen self -dlopen foo1.la
5012 myprog_DEPENDENCIES = $(LTDLDEPS) foo1.la
5016 @defmac LTDL_INSTALLABLE
5017 @defmacx AC_LIBLTDL_INSTALLABLE
5018 These macros are deprecated, the @samp{installable} option to
5019 @code{LTDL_INIT} should be used instead.
5022 @defmac LTDL_CONVENIENCE
5023 @defmacx AC_LIBLTDL_CONVENIENCE
5024 These macros are deprecated, the @samp{convenience} option to
5025 @code{LTDL_INIT} should be used instead.
5029 @node Trace interface
5030 @chapter Libtool's trace interface
5031 @cindex trace interface
5032 @cindex autoconf traces
5034 This section describes macros whose sole purpose is to be traced using
5035 Autoconf's @option{--trace} option (@pxref{autoconf Invocation, , The
5036 Autoconf Manual, autoconf, The Autoconf Manual}) to query the Libtool
5037 configuration of a project. These macros are called by Libtool
5038 internals and should never be called by user code; they should only be
5041 @defmac LT_SUPPORTED_TAG (@var{tag})
5042 This macro is called once for each language enabled in the package. Its
5043 only argument, @var{tag}, is the tag-name corresponding to the language
5046 You can therefore retrieve the list of all tags enabled in a project
5047 using the following command:
5049 autoconf --trace 'LT_SUPPORTED_TAG:$1'
5055 @chapter Frequently Asked Questions about libtool
5057 This chapter covers some questions that often come up on the mailing
5061 * Stripped link flags:: Dropped flags when creating a library
5064 @node Stripped link flags
5065 @section Why does libtool strip link flags when creating a library?
5067 When creating a shared library, but not when compiling or creating
5068 a program, @command{libtool} drops some flags from the command line
5069 provided by the user. This is done because flags unknown to
5070 @command{libtool} may interfere with library creation or require
5071 additional support from @command{libtool}, and because omitting
5072 flags is usually the conservative choice for a successful build.
5074 If you encounter flags that you think are useful to pass, as a
5075 work-around you can prepend flags with @code{-Wc,} or @code{-Xcompiler }
5076 to allow them to be passed through to the compiler driver
5077 (@pxref{Link mode}). Another possibility is to add flags already
5078 to the compiler command at @command{configure} run time:
5081 ./configure CC='gcc -m64'
5084 If you think @command{libtool} should let some flag through by default,
5085 here's how you can test such an inclusion: grab the Libtool development
5086 tree, edit the @file{ltmain.m4sh} file in the @file{libltdl/config}
5087 subdirectory to pass through the flag (search for @samp{Flags to be
5088 passed through}), re-bootstrap and build with the flags in question
5089 added to @code{LDFLAGS}, @code{CFLAGS}, @code{CXXFLAGS}, etc. on the
5090 @command{configure} command line as appropriate. Run the testsuite
5091 as described in the @file{README} file and report results to
5094 @node Troubleshooting
5095 @chapter Troubleshooting
5096 @cindex troubleshooting
5097 @cindex problems, solving
5098 @cindex solving problems
5099 @cindex problems, blaming somebody else for
5101 Libtool is under constant development, changing to remain up-to-date
5102 with modern operating systems. If libtool doesn't work the way you
5103 think it should on your platform, you should read this chapter to help
5104 determine what the problem is, and how to resolve it.
5107 * Libtool test suite:: Libtool's self-tests.
5108 * Reporting bugs:: How to report problems with libtool.
5111 @node Libtool test suite
5112 @section The libtool test suite
5115 Libtool comes with two integrated sets of tests to check that your build
5116 is sane, that test its capabilities, and report obvious bugs in the
5117 libtool program. These tests, too, are constantly evolving, based on
5118 past problems with libtool, and known deficiencies in other operating
5121 As described in the @file{README} file, you may run @kbd{make -k check}
5122 after you have built libtool (possibly before you install it) in order
5123 to make sure that it meets basic functional requirements.
5126 * Test descriptions:: The contents of the old test suite.
5127 * When tests fail:: What to do when a test fails.
5130 @node Test descriptions
5131 @subsection Description of test suite
5133 Here is a list of the current programs in the old test suite, and what
5138 @item cdemo-conf.test
5139 @itemx cdemo-make.test
5140 @itemx cdemo-exec.test
5141 @itemx cdemo-static.test
5142 @itemx cdemo-static-make.test
5143 @itemx cdemo-static-exec.test
5144 @itemx cdemo-shared.test
5145 @itemx cdemo-shared-make.test
5146 @itemx cdemo-shared-exec.test
5147 @itemx cdemo-undef.test
5148 @itemx cdemo-undef-make.test
5149 @itemx cdemo-undef-exec.test
5150 @pindex cdemo-conf.test
5151 @pindex cdemo-make.test
5152 @pindex cdemo-exec.test
5153 @pindex cdemo-static.test
5154 @pindex cdemo-static-make.test
5155 @pindex cdemo-static-exec.test
5156 @pindex cdemo-shared.test
5157 @pindex cdemo-shared-make.test
5158 @pindex cdemo-shared-exec.test
5159 @pindex cdemo-undef.test
5160 @pindex cdemo-undef-make.test
5161 @pindex cdemo-undef-exec.test
5162 These programs check to see that the @file{tests/cdemo} subdirectory of
5163 the libtool distribution can be configured and built correctly.
5165 The @file{tests/cdemo} subdirectory contains a demonstration of libtool
5166 convenience libraries, a mechanism that allows build-time static
5167 libraries to be created, in a way that their components can be later
5168 linked into programs or other libraries, even shared ones.
5170 The tests matching @file{cdemo-*make.test} and @file{cdemo-*exec.test}
5171 are executed three times, under three different libtool configurations:
5172 @file{cdemo-conf.test} configures @file{cdemo/libtool} to build both
5173 static and shared libraries (the default for platforms that support
5174 both), @file{cdemo-static.test} builds only static libraries
5175 (@samp{--disable-shared}), and @file{cdemo-shared.test} builds only
5176 shared libraries (@samp{--disable-static}).
5178 The test @file{cdemo-undef.test} tests the generation of shared
5179 libraries with undefined symbols on systems that allow this.
5181 @item demo-conf.test
5182 @itemx demo-make.test
5183 @itemx demo-exec.test
5184 @itemx demo-inst.test
5185 @itemx demo-unst.test
5186 @itemx demo-static.test
5187 @itemx demo-static-make.test
5188 @itemx demo-static-exec.test
5189 @itemx demo-static-inst.test
5190 @itemx demo-static-unst.test
5191 @itemx demo-shared.test
5192 @itemx demo-shared-make.test
5193 @itemx demo-shared-exec.test
5194 @itemx demo-shared-inst.test
5195 @itemx demo-shared-unst.test
5196 @itemx demo-nofast.test
5197 @itemx demo-nofast-make.test
5198 @itemx demo-nofast-exec.test
5199 @itemx demo-nofast-inst.test
5200 @itemx demo-nofast-unst.test
5201 @itemx demo-pic.test
5202 @itemx demo-pic-make.test
5203 @itemx demo-pic-exec.test
5204 @itemx demo-nopic.test
5205 @itemx demo-nopic-make.test
5206 @itemx demo-nopic-exec.test
5207 @pindex demo-conf.test
5208 @pindex demo-make.test
5209 @pindex demo-exec.test
5210 @pindex demo-inst.test
5211 @pindex demo-unst.test
5212 @pindex demo-static.test
5213 @pindex demo-static-make.test
5214 @pindex demo-static-exec.test
5215 @pindex demo-static-inst.test
5216 @pindex demo-static-unst.test
5217 @pindex demo-shared.test
5218 @pindex demo-shared-make.test
5219 @pindex demo-shared-exec.test
5220 @pindex demo-shared-inst.test
5221 @pindex demo-shared-unst.test
5222 @pindex demo-nofast.test
5223 @pindex demo-nofast-make.test
5224 @pindex demo-nofast-exec.test
5225 @pindex demo-nofast-inst.test
5226 @pindex demo-nofast-unst.test
5227 @pindex demo-pic.test
5228 @pindex demo-pic-make.test
5229 @pindex demo-pic-exec.test
5230 @pindex demo-nopic.test
5231 @pindex demo-nopic-make.test
5232 @pindex demo-nopic-exec.test
5233 These programs check to see that the @file{tests/demo} subdirectory of
5234 the libtool distribution can be configured, built, installed, and
5235 uninstalled correctly.
5237 The @file{tests/demo} subdirectory contains a demonstration of a trivial
5238 package that uses libtool. The tests matching @file{demo-*make.test},
5239 @file{demo-*exec.test}, @file{demo-*inst.test} and
5240 @file{demo-*unst.test} are executed four times, under four different
5241 libtool configurations: @file{demo-conf.test} configures
5242 @file{demo/libtool} to build both static and shared libraries,
5243 @file{demo-static.test} builds only static libraries
5244 (@option{--disable-shared}), and @file{demo-shared.test} builds only
5245 shared libraries (@option{--disable-static}).
5246 @file{demo-nofast.test} configures @file{demo/libtool} to
5247 disable the fast-install mode (@option{--enable-fast-install=no}).
5248 @file{demo-pic.test} configures @file{demo/libtool} to
5249 prefer building PIC code (@option{--with-pic}), @file{demo-nopic.test}
5250 to prefer non-PIC code (@option{--without-pic}).
5252 @item demo-deplibs.test
5253 @pindex demo-deplibs.test
5254 Many systems cannot link static libraries into shared libraries.
5255 libtool uses a @code{deplibs_check_method} to prevent such cases.
5256 This tests checks whether libtool's @code{deplibs_check_method}
5259 @item demo-hardcode.test
5260 @pindex demo-hardcode.test
5261 On all systems with shared libraries, the location of the library can be
5262 encoded in executables that are linked against it @pxref{Linking
5263 executables}. This test checks the conditions under which your system
5264 linker hardcodes the library location, and guarantees that they
5265 correspond to libtool's own notion of how your linker behaves.
5267 @item demo-relink.test
5268 @itemx depdemo-relink.test
5269 @pindex demo-relink.test
5270 @pindex depdemo-relink.test
5271 These tests check whether variable @code{shlibpath_overrides_runpath} is
5272 properly set. If the test fails, it will indicate what the variable should
5275 @item demo-noinst-link.test
5276 @pindex demo-noinst-link.test
5277 Checks whether libtool will not try to link with a previously installed
5278 version of a library when it should be linking with a just-built one.
5280 @item depdemo-conf.test
5281 @itemx depdemo-make.test
5282 @itemx depdemo-exec.test
5283 @itemx depdemo-inst.test
5284 @itemx depdemo-unst.test
5285 @itemx depdemo-static.test
5286 @itemx depdemo-static-make.test
5287 @itemx depdemo-static-exec.test
5288 @itemx depdemo-static-inst.test
5289 @itemx depdemo-static-unst.test
5290 @itemx depdemo-shared.test
5291 @itemx depdemo-shared-make.test
5292 @itemx depdemo-shared-exec.test
5293 @itemx depdemo-shared-inst.test
5294 @itemx depdemo-shared-unst.test
5295 @itemx depdemo-nofast.test
5296 @itemx depdemo-nofast-make.test
5297 @itemx depdemo-nofast-exec.test
5298 @itemx depdemo-nofast-inst.test
5299 @itemx depdemo-nofast-unst.test
5300 @pindex depdemo-conf.test
5301 @pindex depdemo-make.test
5302 @pindex depdemo-exec.test
5303 @pindex depdemo-inst.test
5304 @pindex depdemo-unst.test
5305 @pindex depdemo-static.test
5306 @pindex depdemo-static-make.test
5307 @pindex depdemo-static-exec.test
5308 @pindex depdemo-static-inst.test
5309 @pindex depdemo-static-unst.test
5310 @pindex depdemo-shared.test
5311 @pindex depdemo-shared-make.test
5312 @pindex depdemo-shared-exec.test
5313 @pindex depdemo-shared-inst.test
5314 @pindex depdemo-shared-unst.test
5315 @pindex depdemo-nofast.test
5316 @pindex depdemo-nofast-make.test
5317 @pindex depdemo-nofast-exec.test
5318 @pindex depdemo-nofast-inst.test
5319 @pindex depdemo-nofast-unst.test
5320 These programs check to see that the @file{tests/depdemo} subdirectory
5321 of the libtool distribution can be configured, built, installed, and
5322 uninstalled correctly.
5324 The @file{tests/depdemo} subdirectory contains a demonstration of
5325 inter-library dependencies with libtool. The test programs link some
5326 interdependent libraries.
5328 The tests matching @file{depdemo-*make.test}, @file{depdemo-*exec.test},
5329 @file{depdemo-*inst.test} and @file{depdemo-*unst.test} are executed
5330 four times, under four different libtool configurations:
5331 @file{depdemo-conf.test} configures @file{depdemo/libtool} to build both
5332 static and shared libraries, @file{depdemo-static.test} builds only static
5333 libraries (@option{--disable-shared}), and @file{depdemo-shared.test} builds
5334 only shared libraries (@option{--disable-static}).
5335 @file{depdemo-nofast.test} configures @file{depdemo/libtool} to
5336 disable the fast-install mode (@option{--enable-fast-install=no}).
5338 @item mdemo-conf.test
5339 @itemx mdemo-make.test
5340 @itemx mdemo-exec.test
5341 @itemx mdemo-inst.test
5342 @itemx mdemo-unst.test
5343 @itemx mdemo-static.test
5344 @itemx mdemo-static-make.test
5345 @itemx mdemo-static-exec.test
5346 @itemx mdemo-static-inst.test
5347 @itemx mdemo-static-unst.test
5348 @itemx mdemo-shared.test
5349 @itemx mdemo-shared-make.test
5350 @itemx mdemo-shared-exec.test
5351 @itemx mdemo-shared-inst.test
5352 @itemx mdemo-shared-unst.test
5353 @pindex mdemo-conf.test
5354 @pindex mdemo-make.test
5355 @pindex mdemo-exec.test
5356 @pindex mdemo-inst.test
5357 @pindex mdemo-unst.test
5358 @pindex mdemo-static.test
5359 @pindex mdemo-static-make.test
5360 @pindex mdemo-static-exec.test
5361 @pindex mdemo-static-inst.test
5362 @pindex mdemo-static-unst.test
5363 @pindex mdemo-shared.test
5364 @pindex mdemo-shared-make.test
5365 @pindex mdemo-shared-exec.test
5366 @pindex mdemo-shared-inst.test
5367 @pindex mdemo-shared-unst.test
5368 These programs check to see that the @file{tests/mdemo} subdirectory of
5369 the libtool distribution can be configured, built, installed, and
5370 uninstalled correctly.
5372 The @file{tests/mdemo} subdirectory contains a demonstration of a
5373 package that uses libtool and the system independent dlopen wrapper
5374 @file{libltdl} to load modules. The library @file{libltdl} provides a
5375 dlopen wrapper for various platforms (POSIX)
5376 including support for dlpreopened modules (@pxref{Dlpreopening}).
5378 The tests matching @file{mdemo-*make.test}, @file{mdemo-*exec.test},
5379 @file{mdemo-*inst.test} and @file{mdemo-*unst.test} are executed
5380 three times, under three different libtool configurations:
5381 @file{mdemo-conf.test} configures @file{mdemo/libtool} to build both
5382 static and shared libraries, @file{mdemo-static.test} builds only static
5383 libraries (@option{--disable-shared}), and @file{mdemo-shared.test} builds
5384 only shared libraries (@option{--disable-static}).
5386 @item mdemo-dryrun.test
5387 @pindex mdemo-dryrun.test
5388 This test checks whether libtool's @option{--dry-run} mode works properly.
5390 @item mdemo2-conf.test
5391 @itemx mdemo2-exec.test
5392 @itemx mdemo2-make.test
5393 @pindex mdemo2-conf.test
5394 @pindex mdemo2-exec.test
5395 @pindex mdemo2-make.test
5396 These programs check to see that the @file{tests/mdemo2} subdirectory of
5397 the libtool distribution can be configured, built, and executed
5400 The @file{tests/mdemo2} directory contains a demonstration of a package
5401 that attempts to link with a library (from the @file{tests/mdemo}
5402 directory) that itself does dlopening of libtool modules.
5406 This test guarantees that linking directly against a non-libtool static
5407 library works properly.
5411 This test makes sure that files ending in @file{.lo} are never linked
5412 directly into a program file.
5416 Check whether we can actually get help for libtool.
5418 @item objectlist.test
5419 @pindex objectlist.test
5420 Check that a nonexistent objectlist file is properly detected.
5422 @item pdemo-conf.test
5423 @itemx pdemo-make.test
5424 @itemx pdemo-exec.test
5425 @itemx pdemo-inst.test
5426 @pindex pdemo-conf.test
5427 @pindex pdemo-make.test
5428 @pindex pdemo-exec.test
5429 @pindex pdemo-inst.test
5430 These programs check to see that the @file{tests/pdemo} subdirectory of
5431 the libtool distribution can be configured, built, and executed
5434 The @file{pdemo-conf.test} lowers the @code{max_cmd_len} variable in the
5435 generated libtool script to test the measures to evade command line
5440 This program checks libtool's metacharacter quoting.
5444 Checks for some nonportable or dubious or undesired shell constructs in
5449 When other programming languages are used with libtool (@pxref{Other
5450 languages}), the source files may end in suffixes other than @file{.c}.
5451 This test validates that libtool can handle suffixes for all the file
5452 types that it supports, and that it fails when the suffix is invalid.
5454 @item tagdemo-conf.test
5455 @itemx tagdemo-make.test
5456 @itemx tagdemo-exec.test
5457 @itemx tagdemo-static.test
5458 @itemx tagdemo-static-make.test
5459 @itemx tagdemo-static-exec.test
5460 @itemx tagdemo-shared.test
5461 @itemx tagdemo-shared-make.test
5462 @itemx tagdemo-shared-exec.test
5463 @itemx tagdemo-undef.test
5464 @itemx tagdemo-undef-make.test
5465 @itemx tagdemo-undef-exec.test
5466 @pindex tagdemo-conf.test
5467 @pindex tagdemo-make.test
5468 @pindex tagdemo-exec.test
5469 @pindex tagdemo-static.test
5470 @pindex tagdemo-static-make.test
5471 @pindex tagdemo-static-exec.test
5472 @pindex tagdemo-shared.test
5473 @pindex tagdemo-shared-make.test
5474 @pindex tagdemo-shared-exec.test
5475 @pindex tagdemo-undef.test
5476 @pindex tagdemo-undef-make.test
5477 @pindex tagdemo-undef-exec.test
5478 These programs check to see that the @file{tests/tagdemo} subdirectory
5479 of the libtool distribution can be configured, built, and executed
5482 The @file{tests/tagdemo} directory contains a demonstration of a package
5483 that uses libtool's multi-language support through configuration tags.
5484 It generates a library from C++ sources, which is then linked to a C++
5487 @item f77demo-conf.test
5488 @itemx f77demo-make.test
5489 @itemx f77demo-exec.test
5490 @itemx f77demo-static.test
5491 @itemx f77demo-static-make.test
5492 @itemx f77demo-static-exec.test
5493 @itemx f77demo-shared.test
5494 @itemx f77demo-shared-make.test
5495 @itemx f77demo-shared-exec.test
5496 @pindex f77demo-conf.test
5497 @pindex f77demo-make.test
5498 @pindex f77demo-exec.test
5499 @pindex f77demo-static.test
5500 @pindex f77demo-static-make.test
5501 @pindex f77demo-static-exec.test
5502 @pindex f77demo-shared.test
5503 @pindex f77demo-shared-make.test
5504 @pindex f77demo-shared-exec.test
5505 These programs check to see that the @file{tests/f77demo} subdirectory
5506 of the libtool distribution can be configured, built, and executed
5509 The @file{tests/f77demo} tests test Fortran 77 support in libtool by
5510 creating libraries from Fortran 77 sources, and mixed Fortran and C
5511 sources, and a Fortran 77 program to use the former library, and a C
5512 program to use the latter library.
5514 @item fcdemo-conf.test
5515 @itemx fcdemo-make.test
5516 @itemx fcdemo-exec.test
5517 @itemx fcdemo-static.test
5518 @itemx fcdemo-static-make.test
5519 @itemx fcdemo-static-exec.test
5520 @itemx fcdemo-shared.test
5521 @itemx fcdemo-shared-make.test
5522 @itemx fcdemo-shared-exec.test
5523 @pindex fcdemo-conf.test
5524 @pindex fcdemo-make.test
5525 @pindex fcdemo-exec.test
5526 @pindex fcdemo-static.test
5527 @pindex fcdemo-static-make.test
5528 @pindex fcdemo-static-exec.test
5529 @pindex fcdemo-shared.test
5530 @pindex fcdemo-shared-make.test
5531 @pindex fcdemo-shared-exec.test
5532 These programs check to see that the @file{tests/fcdemo} subdirectory
5533 of the libtool distribution can be configured, built, and executed
5536 The @file{tests/fcdemo} is similar to the @file{tests/f77demo}
5537 directory, except that Fortran 90 is used in combination with the
5538 @samp{FC} interface provided by Autoconf and Automake.
5542 The new, Autotest-based test suite uses keywords to classify certain
5550 The test group exercises one of these @command{libtool} language tags.
5554 These keywords denote that the respective external program is needed
5555 by the test group. The tests are typically skipped if the program is
5556 not installed. The @samp{automake} keyword may also denote use of the
5557 @command{aclocal} program.
5560 This test group may require user interaction on some systems. Typically,
5561 this means closing a popup window about a DLL load error on Windows.
5564 Denote that the @file{libltdl} library is exercised by the test group.
5568 Denote that the @command{libtool} or @command{libtoolize} scripts are
5569 exercised by the test group, respectively.
5572 Denote that this test group may recursively re-invoke the test suite
5573 itself, with changed settings and maybe a changed @command{libtool}
5574 script. You may use the @env{INNER_TESTSUITEFLAGS} variable to pass
5575 additional settings to this recursive invocation. Typically, recursive
5576 invocations delimit the set of tests with another keyword, for example
5577 by passing @code{-k libtool} right before the expansion of the
5578 @env{INNER_TESTSUITEFLAGS} variable (without an intervening space, so
5579 you get the chance for further delimitation).
5581 Test groups with the keyword @samp{recursive} should not be denoted with
5582 keywords, in order to avoid infinite recursion. As a consequence,
5583 recursive test groups themselves should never require user interaction,
5584 while the test groups they invoke may do so.
5587 @cindex @samp{check-interactive}
5588 @cindex @samp{check-noninteractive}
5589 There is a convenience target @samp{check-noninteractive} that runs
5590 all tests from both test suites that do not cause user interaction on
5591 Windows. Conversely, the target @samp{check-interactive} runs the
5592 complement of tests and might require closing popup windows about DLL
5593 load errors on Windows.
5596 @node When tests fail
5597 @subsection When tests fail
5598 @cindex failed tests
5599 @cindex tests, failed
5601 When the tests in the old test suite are run via @command{make check},
5602 output is caught in per-test @file{tests/@var{test-name}.log} files
5603 and summarized in the @file{test-suite.log} file. The exit status of each
5604 program tells the @file{Makefile} whether or not the test succeeded.
5606 If a test fails, it means that there is either a programming error in
5607 libtool, or in the test program itself.
5609 To investigate a particular test, you may run it directly, as you would
5610 a normal program. When the test is invoked in this way, it produces
5611 output that may be useful in determining what the problem is.
5613 The new, Autotest-based test suite produces as output a file
5614 @file{tests/testsuite.log} which contains information about failed
5617 You can pass options to the test suite through the @command{make}
5618 variable @env{TESTSUITEFLAGS} (@pxref{testsuite Invocation, ,
5619 The Autoconf Manual, autoconf, The Autoconf Manual}).
5622 @node Reporting bugs
5623 @section Reporting bugs
5625 @cindex reporting bugs
5626 @cindex problem reports
5628 If you think you have discovered a bug in libtool, you should think
5629 twice: the libtool maintainer is notorious for passing the buck (or
5630 maybe that should be ``passing the bug''). Libtool was invented to fix
5631 known deficiencies in shared library implementations, so, in a way, most
5632 of the bugs in libtool are actually bugs in other operating systems.
5633 However, the libtool maintainer would definitely be happy to add support
5634 for somebody else's buggy operating system. [I wish there was a good
5635 way to do winking smiley-faces in Texinfo.]
5637 Genuine bugs in libtool include problems with shell script portability,
5638 documentation errors, and failures in the test suite (@pxref{Libtool
5641 First, check the documentation and help screens to make sure that the
5642 behaviour you think is a problem is not already mentioned as a feature.
5644 Then, you should read the Emacs guide to reporting bugs (@pxref{Bugs, ,
5645 Reporting Bugs, emacs, The Emacs Manual}). Some of the details
5646 listed there are specific to Emacs, but the principle behind them is a
5649 Finally, send a bug report to @value{BUGADDR} with any appropriate
5650 @emph{facts}, such as test suite output (@pxref{When tests fail}), all
5651 the details needed to reproduce the bug, and a brief description of why
5652 you think the behaviour is a bug. Be sure to include the word
5653 ``libtool'' in the subject line, as well as the version number you are
5654 using (which can be found by typing @kbd{libtool --version}).
5657 @chapter Maintenance notes for libtool
5659 This chapter contains information that the libtool maintainer finds
5660 important. It will be of no use to you unless you are considering
5661 porting libtool to new systems, or writing your own libtool.
5664 * New ports:: How to port libtool to new systems.
5665 * Tested platforms:: When libtool was last tested.
5666 * Platform quirks:: Information about different library systems.
5667 * libtool script contents:: Configuration information that libtool uses.
5668 * Cheap tricks:: Making libtool maintainership easier.
5672 @section Porting libtool to new systems
5674 Before you embark on porting libtool to an unsupported system, it is
5675 worthwhile to send e-mail to @value{MAILLIST}, to make sure that you are
5676 not duplicating existing work.
5678 If you find that any porting documentation is missing, please complain!
5679 Complaints with patches and improvements to the documentation, or to
5680 libtool itself, are more than welcome.
5683 * Information sources:: Where to find relevant documentation
5684 * Porting inter-library dependencies:: Implementation details explained
5687 @node Information sources
5688 @subsection Information sources
5690 Once it is clear that a new port is necessary, you'll generally need the
5691 following information:
5694 @item canonical system name
5695 You need the output of @code{config.guess} for this system, so that you
5696 can make changes to the libtool configuration process without affecting
5699 @item man pages for @command{ld} and @command{cc}
5700 These generally describe what flags are used to generate PIC, to create
5701 shared libraries, and to link against only static libraries. You may
5702 need to follow some cross references to find the information that is
5705 @item man pages for @command{ld.so}, @command{rtld}, or equivalent
5706 These are a valuable resource for understanding how shared libraries are
5707 loaded on the system.
5709 @item man page for @command{ldconfig}, or equivalent
5710 This page usually describes how to install shared libraries.
5712 @item output from @kbd{ls -l /lib /usr/lib}
5713 This shows the naming convention for shared libraries on the system,
5714 including which names should be symbolic links.
5716 @item any additional documentation
5717 Some systems have special documentation on how to build and install
5721 If you know how to program the Bourne shell, then you can complete the
5722 port yourself; otherwise, you'll have to find somebody with the relevant
5723 skills who will do the work. People on the libtool mailing list are
5724 usually willing to volunteer to help you with new ports, so you can send
5725 the information to them.
5727 To do the port yourself, you'll definitely need to modify the
5728 @code{libtool.m4} macros in order to make platform-specific changes to
5729 the configuration process. You should search that file for the
5730 @code{PORTME} keyword, which will give you some hints on what you'll
5731 need to change. In general, all that is involved is modifying the
5732 appropriate configuration variables (@pxref{libtool script contents}).
5734 Your best bet is to find an already-supported system that is similar to
5735 yours, and make your changes based on that. In some cases, however,
5736 your system will differ significantly from every other supported system,
5737 and it may be necessary to add new configuration variables, and modify
5738 the @code{ltmain.in} script accordingly. Be sure to write to the
5739 mailing list before you make changes to @code{ltmain.in}, since they may
5740 have advice on the most effective way of accomplishing what you want.
5742 @node Porting inter-library dependencies
5743 @subsection Porting inter-library dependencies support
5744 @cindex inter-library dependency
5745 @vindex deplibs_check_method
5747 Since version 1.2c, libtool has re-introduced the ability to do
5748 inter-library dependency on some platforms, thanks to a patch by Toshio
5749 Kuratomi @email{badger@@prtr-13.ucsc.edu}. Here's a shortened version
5750 of the message that contained his patch:
5752 The basic architecture is this: in @file{libtool.m4}, the person who
5753 writes libtool makes sure @samp{$deplibs} is included in
5754 @samp{$archive_cmds} somewhere and also sets the variable
5755 @samp{$deplibs_check_method}, and maybe @samp{$file_magic_cmd} when
5756 @samp{deplibs_check_method} is file_magic.
5758 @samp{deplibs_check_method} can be one of five things:
5760 @item file_magic [@var{regex}]
5762 @vindex file_magic_cmd
5763 @vindex file_magic_test_file
5764 looks in the library link path for libraries that have the right
5765 libname. Then it runs @samp{$file_magic_cmd} on the library and checks
5766 for a match against the extended regular expression @var{regex}. When
5767 @code{file_magic_test_file} is set by @file{libtool.m4}, it is used as an
5768 argument to @samp{$file_magic_cmd} in order to verify whether the
5769 regular expression matches its output, and warn the user otherwise.
5772 @vindex test_compile
5773 just checks whether it is possible to link a program out of a list of
5774 libraries, and checks which of those are listed in the output of
5775 @code{ldd}. It is currently unused, and will probably be dropped in the
5780 will pass everything without any checking. This may work on platforms
5781 in which code is position-independent by default and inter-library
5782 dependencies are properly supported by the dynamic linker, for example,
5783 on DEC OSF/1 3 and 4.
5787 It causes deplibs to be reassigned @samp{deplibs=""}. That way
5788 @samp{archive_cmds} can contain deplibs on all platforms, but not have
5789 deplibs used unless needed.
5793 is the default for all systems unless overridden in @file{libtool.m4}.
5794 It is the same as @samp{none}, but it documents that we really don't
5795 know what the correct value should be, and we welcome patches that
5799 Then in @file{ltmain.in} we have the real workhorse: a little
5800 initialization and postprocessing (to setup/release variables for use
5801 with eval echo libname_spec etc.) and a case statement that decides
5802 the method that is being used. This is the real code@dots{} I wish I could
5803 condense it a little more, but I don't think I can without function
5804 calls. I've mostly optimized it (moved things out of loops, etc.) but
5805 there is probably some fat left. I thought I should stop while I was
5806 ahead, work on whatever bugs you discover, etc.@: before thinking about
5807 more than obvious optimizations.
5809 @node Tested platforms
5810 @section Tested platforms
5812 This table describes when libtool was last known to be tested on
5813 platforms where it claims to support shared libraries:
5819 Note: The vendor-distributed HP-UX @command{sed}(1) programs are horribly
5820 broken, and cannot handle libtool's requirements, so users may report
5821 unusual problems. There is no workaround except to install a working
5822 @command{sed} (such as GNU @command{sed}) on these systems.
5824 Note: The vendor-distributed NCR MP-RAS @command{cc} programs emits
5825 copyright on standard error that confuse tests on size of
5826 @file{conftest.err}. The workaround is to specify @code{CC}
5827 when run @code{configure} with @kbd{CC='cc -Hnocopyr'}.
5829 @node Platform quirks
5830 @section Platform quirks
5832 This section is dedicated to the sanity of the libtool maintainers. It
5833 describes the programs that libtool uses, how they vary from system to
5834 system, and how to test for them.
5836 Because libtool is a shell script, it can be difficult to understand
5837 just by reading it from top to bottom. This section helps show why
5838 libtool does things a certain way. Combined with the scripts
5839 themselves, you should have a better sense of how to improve libtool, or
5843 * References:: Finding more information.
5844 * Compilers:: Creating object files from source files.
5845 * Reloadable objects:: Binding object files together.
5846 * Multiple dependencies:: Removing duplicate dependent libraries.
5847 * Archivers:: Programs that create static archives.
5848 * Cross compiling:: Issues that arise when cross compiling.
5849 * File name conversion:: Converting file names between platforms.
5850 * Windows DLLs:: Windows header defines.
5854 @subsection References
5856 The following is a list of valuable documentation references:
5860 SGI's IRIX Manual Pages can be found at@*
5861 @url{http://techpubs.sgi.com/cgi-bin/infosrch.cgi?cmd=browse&db=man}.
5864 Sun's free service area
5865 (@url{http://www.sun.com/service/online/free.html}) and documentation
5866 server (@url{http://docs.sun.com/}).
5869 Compaq's Tru64 UNIX online documentation is at@*
5870 (@url{http://tru64unix.compaq.com/faqs/publications/pub_page/doc_list.html})
5871 with C++ documentation at@*
5872 (@url{http://tru64unix.compaq.com/cplus/docs/index.htm}).
5875 Hewlett-Packard has online documentation at
5876 (@url{http://docs.hp.com/index.html}).
5879 IBM has online documentation at
5880 (@url{http://www.rs6000.ibm.com/resource/aix_resource/Pubs/}).
5884 @subsection Compilers
5886 The only compiler characteristics that affect libtool are the flags
5887 needed (if any) to generate PIC objects. In general, if a C compiler
5888 supports certain PIC flags, then any derivative compilers support the
5889 same flags. Until there are some noteworthy exceptions to this rule,
5890 this section will document only C compilers.
5892 The following C compilers have standard command line options, regardless
5898 This is the GNU C compiler, which is also the system compiler for many
5899 free operating systems (FreeBSD, GNU/Hurd, GNU/Linux, Lites, NetBSD, and
5900 OpenBSD, to name a few).
5902 The @option{-fpic} or @option{-fPIC} flags can be used to generate
5903 position-independent code. @option{-fPIC} is guaranteed to generate
5904 working code, but the code is slower on m68k, m88k, and Sparc chips.
5905 However, using @option{-fpic} on those chips imposes arbitrary size limits
5906 on the shared libraries.
5909 The rest of this subsection lists compilers by the operating system that
5910 they are bundled with:
5912 @c FIXME these should all be better-documented
5917 Most AIX compilers have no PIC flags, since AIX (with the exception of
5918 AIX for IA-64) runs on PowerPC and RS/6000 chips. @footnote{All code compiled
5919 for the PowerPC and RS/6000 chips (@code{powerpc-*-*}, @code{powerpcle-*-*},
5920 and @code{rs6000-*-*}) is position-independent, regardless of the operating
5921 system or compiler suite. So, ``regular objects'' can be used to build
5922 shared libraries on these systems and no special PIC compiler flags are
5926 Use @samp{+Z} to generate PIC.
5929 Digital/UNIX 3.x does not have PIC flags, at least not on the PowerPC
5933 Use @option{-KPIC} to generate PIC.
5936 Use @option{-PIC} to generate PIC.
5939 @node Reloadable objects
5940 @subsection Reloadable objects
5942 On all known systems, a reloadable object can be created by running
5943 @kbd{ld -r -o @var{output}.o @var{input1}.o @var{input2}.o}. This
5944 reloadable object may be treated as exactly equivalent to other
5947 @node Multiple dependencies
5948 @subsection Multiple dependencies
5950 On most modern platforms the order in which dependent libraries are listed
5951 has no effect on object generation. In theory, there are platforms
5952 that require libraries that provide missing symbols to other libraries
5953 to be listed after those libraries whose symbols they provide.
5955 Particularly, if a pair of static archives each resolve some of the
5956 other's symbols, it might be necessary to list one of those archives
5957 both before and after the other one. Libtool does not currently cope
5958 with this situation well, since duplicate libraries are removed from
5959 the link line by default. Libtool provides the command line option
5960 @option{--preserve-dup-deps} to preserve all duplicate dependencies
5961 in cases where it is necessary.
5964 @subsection Archivers
5966 On all known systems, building a static library can be accomplished by
5967 running @kbd{ar cru lib@var{name}.a @var{obj1}.o @var{obj2}.o @dots{}},
5968 where the @file{.a} file is the output library, and each @file{.o} file is an
5971 On all known systems, if there is a program named @command{ranlib}, then it
5972 must be used to ``bless'' the created library before linking against it,
5973 with the @kbd{ranlib lib@var{name}.a} command. Some systems, like Irix,
5974 use the @code{ar ts} command, instead.
5976 @node Cross compiling
5977 @subsection Cross compiling
5978 @cindex cross compile
5980 Most build systems support the ability to compile libraries and applications
5981 on one platform for use on a different platform, provided a compiler capable
5982 of generating the appropriate output is available. In such cross compiling
5983 scenarios, the platform on which the libraries or applications are compiled
5984 is called the @dfn{build platform}, while the platform on which the libraries
5985 or applications are intended to be used or executed is called the
5986 @dfn{host platform}.
5987 @ref{GNU Build System,, The GNU Build System, automake, The Automake Manual},
5988 of which libtool is a part, supports cross compiling via arguments passed to
5989 the configure script: @option{--build=...} and @option{--host=...}. However,
5990 when the build platform and host platform are very different, libtool is
5991 required to make certain accommodations to support these scenarios.
5993 In most cases, because the build platform and host platform differ, the
5994 cross-compiled libraries and executables can't be executed or tested on the
5995 build platform where they were compiled. The testsuites of most build systems
5996 will often skip any tests that involve executing such foreign executables when
5997 cross-compiling. However, if the build platform and host platform are
5998 sufficiently similar, it is often possible to run cross-compiled applications.
5999 Libtool's own testsuite often attempts to execute cross-compiled tests, but
6000 will mark any failures as @emph{skipped} since the failure might simply be due
6001 to the differences between the two platforms.
6003 In addition to cases where the host platform and build platform are extremely
6004 similar (e.g. @samp{i586-pc-linux-gnu} and @samp{i686-pc-linux-gnu}), there is
6005 another case in which cross-compiled host applications may be executed on the
6006 build platform. This is possible when the build platform supports an emulation
6007 or API-enhanced environment for the host platform. One example of this
6008 situation would be if the build platform were MinGW, and the host platform were
6009 Cygwin (or vice versa). Both of these platforms can actually operate within a
6010 single Windows instance, so Cygwin applications can be launched from a MinGW
6011 context, and vice versa---provided certain care is taken. Another example
6012 would be if the build platform were GNU/Linux on an x86 32bit processor, and
6013 the host platform were MinGW. In this situation, the
6014 @uref{http://www.winehq.org/, Wine} environment can be used to launch Windows
6015 applications from the GNU/Linux operating system; again, provided certain care
6018 One particular issue occurs when a Windows platform such as MinGW, Cygwin, or
6019 MSYS is the host or build platform, while the other platform is a Unix-style
6020 system. In these cases, there are often conflicts between the format of the
6021 file names and paths expected within host platform libraries and executables,
6022 and those employed on the build platform.
6024 This situation is best described using a concrete example: suppose the build
6025 platform is GNU/Linux with canonical triplet @samp{i686-pc-linux-gnu}. Suppose
6026 further that the host platform is MinGW with canonical triplet
6027 @samp{i586-pc-mingw32}. On the GNU/Linux platform there is a cross compiler
6028 following the usual naming conventions of such compilers, where the compiler
6029 name is prefixed by the host canonical triplet (or suitable alias). (For more
6030 information concerning canonical triplets and platform aliases, see
6031 @ref{Specifying Target Triplets,, Specifying Target Triplets, autoconf,
6032 The Autoconf Manual} and @ref{Canonicalizing,, Canonicalizing, autoconf,
6033 The Autoconf Manual}) In this case, the C compiler is named
6034 @samp{i586-pc-mingw32-gcc}.
6036 As described in @ref{Wrapper executables}, for the MinGW host platform libtool
6037 uses a wrapper executable to set various environment variables before launching
6038 the actual program executable. Like the program executable, the wrapper
6039 executable is cross-compiled for the host platform (that is, for MinGW). As
6040 described above, ordinarily a host platform executable cannot be executed on
6041 the build platform, but in this case the Wine environment could be used to
6042 launch the MinGW application from GNU/Linux. However, the wrapper executable,
6043 as a host platform (MinGW) application, must set the @env{PATH} variable so
6044 that the true application's dependent libraries can be located---but the
6045 contents of the @env{PATH} variable must be structured for MinGW. Libtool
6046 must use the Wine file name mapping facilities to determine the correct value
6047 so that the wrapper executable can set the @env{PATH} variable to point to the
6050 For example, suppose we are compiling an application in @file{/var/tmp} on
6051 GNU/Linux, using separate source code and build directories:
6054 @multitable @columnfractions 0.5 0.5
6055 @item @file{/var/tmp/foo-1.2.3/app/} @tab (application source code)
6056 @item @file{/var/tmp/foo-1.2.3/lib/} @tab (library source code)
6057 @item @file{/var/tmp/BUILD/app/} @tab (application build objects here)
6058 @item @file{/var/tmp/BUILD/lib/} @tab (library build objects here)
6062 Since the library will be built in @file{/var/tmp/BUILD/lib}, the wrapper
6063 executable (which will be in @file{/var/tmp/BUILD/app}) must add that
6064 directory to @env{PATH} (actually, it must add the directory named
6065 @var{objdir} under @file{/var/tmp/BUILD/lib}, but we'll ignore that detail
6066 for now). However, Windows does not have a concept of Unix-style file or
6067 directory names such as @file{/var/tmp/BUILD/lib}. Therefore, Wine provides
6068 a mapping from Windows file names such as @file{C:\Program Files} to specific
6069 Unix-style file names. Wine also provides a utility that can be used to map
6070 Unix-style file names to Windows file names.
6072 In this case, the wrapper executable should actually add the value
6075 Z:\var\tmp\BUILD\lib
6079 to the @env{PATH}. libtool contains support for path conversions of this
6080 type, for a certain limited set of build and host platform combinations. In
6081 this case, libtool will invoke Wine's @command{winepath} utility to ensure that
6082 the correct @env{PATH} value is used. For more information, see
6083 @pxref{File name conversion}.
6085 @node File name conversion
6086 @subsection File name conversion
6087 @cindex file name conversion
6088 @cindex path conversion
6090 In certain situations, libtool must convert file names and paths between
6091 formats appropriate to different platforms. Usually this occurs when
6092 cross-compiling, and affects only the ability to launch host platform
6093 executables on the build platform using an emulation or API-enhancement
6094 environment such as Wine. Failure to convert paths
6095 (@pxref{File Name Conversion Failure}) will cause a warning to be issued, but
6096 rarely causes the build to fail---and should have no affect on the compiled
6097 products, once installed properly on the host platform. For more information,
6098 @pxref{Cross compiling}.
6100 However, file name conversion may also occur in another scenario: when using a
6101 Unix emulation system on Windows (such as Cygwin or MSYS), combined with a
6102 native Windows compiler such as MinGW or MSVC. Only a limited set of such
6103 scenarios are currently supported; in other cases file name conversion is
6104 skipped. The lack of file name conversion usually means that uninstalled
6105 executables can't be launched, but only rarely causes the build to fail
6106 (@pxref{File Name Conversion Failure}).
6108 libtool supports file name conversion in the following scenarios:
6110 @multitable @columnfractions .25 .25 .5
6111 @headitem build platform @tab host platform @tab Notes
6112 @item MinGW (MSYS) @tab MinGW (Windows)
6113 @tab @pxref{Native MinGW File Name Conversion}
6115 @item Cygwin @tab MinGW (Windows)
6116 @tab @pxref{Cygwin/Windows File Name Conversion}
6118 @item Unix + Wine @tab MinGW (Windows)
6119 @tab Requires Wine. @pxref{Unix/Windows File Name Conversion}
6121 @item MinGW (MSYS) @tab Cygwin
6122 @tab Requires @env{LT_CYGPATH}. @pxref{LT_CYGPATH}. Provided for testing
6125 @item Unix + Wine @tab Cygwin
6126 @tab Requires both Wine and @env{LT_CYGPATH}, but does not yet work with
6127 Cygwin 1.7.7 and Wine-1.2.
6128 See @pxref{Unix/Windows File Name Conversion} and @pxref{LT_CYGPATH}.
6132 * File Name Conversion Failure:: What happens when file name conversion fails
6133 * Native MinGW File Name Conversion:: MSYS file name conversion idiosyncrasies
6134 * Cygwin/Windows File Name Conversion:: Using @command{cygpath} to convert Cygwin file names
6135 * Unix/Windows File Name Conversion:: Using Wine to convert Unix paths
6136 * LT_CYGPATH:: Invoking @command{cygpath} from other environments
6137 * Cygwin to MinGW Cross:: Other notes concerning MinGW cross
6140 @node File Name Conversion Failure
6141 @subsubsection File Name Conversion Failure
6142 @cindex File Name Conversion - Failure
6143 @cindex Path Conversion - Failure
6145 In most cases, file name conversion is not needed or attempted. However, when
6146 libtool detects that a specific combination of build and host platform does
6147 require file name conversion, it is possible that the conversion may fail.
6148 In these cases, you may see a warning such as the following:
6151 Could not determine the host file name corresponding to
6152 `... a file name ...'
6153 Continuing, but uninstalled executables may not work.
6160 Could not determine the host path corresponding to
6162 Continuing, but uninstalled executables may not work.
6166 This should not cause the build to fail. At worst, it means that the wrapper
6167 executable will specify file names or paths appropriate for the build platform.
6168 Since those are not appropriate for the host platform, the uninstalled
6169 executables would not operate correctly, even when the wrapper executable is
6170 launched via the appropriate emulation or API-enhancement (e.g. Wine). Simply
6171 install the executables on the host platform, and execute them there.
6173 @node Native MinGW File Name Conversion
6174 @subsubsection Native MinGW File Name Conversion
6175 @cindex File Name Conversion - MinGW
6176 @cindex Path Conversion - MinGW
6179 MSYS is a Unix emulation environment for Windows, and is specifically designed
6180 such that in normal usage it @emph{pretends} to be MinGW or native Windows,
6181 but understands Unix-style file names and paths, and supports standard Unix
6182 tools and shells. Thus, ``native'' MinGW builds are actually an odd sort of
6183 cross-compile, from an MSYS Unix emulation environment ``pretending'' to be
6184 MinGW, to actual native Windows.
6186 When an MSYS shell launches a native Windows executable (as opposed to other
6187 @emph{MSYS} executables), it uses a system of heuristics to detect any
6188 command-line arguments that contain file names or paths. It automatically
6189 converts these file names from the MSYS (Unix-like) format, to the
6190 corresponding Windows file name, before launching the executable. However,
6191 this auto-conversion facility is only available when using the MSYS runtime
6192 library. The wrapper executable itself is a MinGW application (that is, it
6193 does not use the MSYS runtime library). The wrapper executable must set
6194 @env{PATH} to, and call @code{_spawnv} with, values that have already been
6195 converted from MSYS format to Windows. Thus, when libtool writes the source
6196 code for the wrapper executable, it must manually convert MSYS paths to
6197 Windows format, so that the Windows values can be hard-coded into the wrapper
6200 @node Cygwin/Windows File Name Conversion
6201 @subsubsection Cygwin/Windows File Name Conversion
6202 @cindex File Name Conversion - Cygwin to Windows
6203 @cindex Path Conversion - Cygwin to Windows
6205 Cygwin provides a Unix emulation environment for Windows. As part of that
6206 emulation, it provides a file system mapping that presents the Windows file
6207 system in a Unix-compatible manner. Cygwin also provides a utility
6208 @command{cygpath} that can be used to convert file names and paths between
6209 the two representations. In a correctly configured Cygwin installation,
6210 @command{cygpath} is always present, and is in the @env{PATH}.
6212 Libtool uses @command{cygpath} to convert from Cygwin (Unix-style) file names
6213 and paths to Windows format when the build platform is Cygwin and the host
6216 When the host platform is Cygwin, but the build platform is MSYS or some Unix
6217 system, libtool also uses @command{cygpath} to convert from Windows to Cygwin
6218 format (after first converting from the build platform format to Windows format;
6219 see @pxref{Native MinGW File Name Conversion} and
6220 @pxref{Unix/Windows File Name Conversion}). Because the build platform is not
6221 Cygwin, @command{cygpath} is not (and should not be) in the @env{PATH}.
6222 Therefore, in this configuration the environment variable @env{LT_CYGPATH} is
6223 required. @xref{LT_CYGPATH}.
6225 @node Unix/Windows File Name Conversion
6226 @subsubsection Unix/Windows File Name Conversion
6227 @cindex File Name Conversion - Unix to Windows
6228 @cindex Path Conversion - Unix to Windows
6231 @uref{http://www.winehq.org/, Wine} provides an interpretation environment for
6232 some Unix platforms in which Windows applications can be executed. It provides
6233 a mapping between the Unix file system and a virtual Windows file system used
6234 by the Windows programs. For the file name conversion to work, Wine must be
6235 installed and properly configured on the build platform, and the
6236 @command{winepath} application must be in the build platform's @env{PATH}. In
6237 addition, on 32bit GNU/Linux it is usually helpful if the binfmt extension is
6241 @subsubsection LT_CYGPATH
6244 For some cross-compile configurations (where the host platform is Cygwin), the
6245 @command{cygpath} program is used to convert file names from the build platform
6246 notation to the Cygwin form (technically, this conversion is from Windows
6247 notation to Cygwin notation; the conversion from the build platform format
6248 to Windows notation is performed via other means). However, because the
6249 @command{cygpath} program is not (and should not be) in the @env{PATH} on
6250 the build platform, @env{LT_CYGPATH} must specify the full build platform
6251 file name (that is, the full Unix or MSYS file name) of the @command{cygpath}
6254 The reason @command{cygpath} should not be in the build platform @env{PATH} is
6255 twofold: first, @command{cygpath} is usually installed in the same directory as
6256 many other Cygwin executables, such as @command{sed}, @command{cp}, etc. If
6257 the build platform environment had this directory in its @env{PATH}, then these
6258 Cygwin versions of common Unix utilities might be used in preference to the
6259 ones provided by the build platform itself, with deleterious effects. Second,
6260 especially when Cygwin-1.7 or later is used, multiple Cygwin installations can
6261 coexist within the same Windows instance. Each installation will have separate
6262 ``mount tables'' specified in @file{@var{CYGROOT-N}/etc/fstab}. These
6263 @dfn{mount tables} control how that instance of Cygwin will map Windows file
6264 names and paths to Cygwin form. Each installation's @command{cygpath} utility
6265 automatically deduces the appropriate @file{/etc/fstab} file. Since each
6266 @file{@var{CYGROOT-N}/etc/fstab} mount table may specify different mappings, it
6267 matters which @command{cygpath} is used.
6269 Note that @command{cygpath} is a Cygwin application; to execute this tool from
6270 Unix requires a working and properly configured Wine installation, as well
6271 as enabling the GNU/Linux @code{binfmt} extension. Furthermore, the Cygwin
6272 @command{setup.exe} tool should have been used, via Wine, to properly install
6273 Cygwin into the Wine file system (and registry).
6275 Unfortunately, Wine support for Cygwin is intermittent. Recent releases of
6276 Cygwin (1.7 and above) appear to require more Windows API support than Wine
6277 provides (as of Wine version 1.2); most Cygwin applications fail to execute.
6278 This includes @command{cygpath} itself. Hence, it is best @emph{not} to use
6279 the LT_CYGPATH machinery in libtool when performing Unix to Cygwin
6280 cross-compiles. Similarly, it is best @emph{not} to enable the GNU/Linux binfmt
6281 support in this configuration, because while Wine will fail to execute the
6282 compiled Cygwin applications, it will still exit with status zero. This tends
6283 to confuse build systems and test suites (including libtool's own testsuite,
6284 resulting in spurious reported failures). Wine support for the older
6285 Cygwin-1.5 series appears satisfactory, but the Cygwin team no longer supports
6286 Cygwin-1.5. It is hoped that Wine will eventually be improved such that
6287 Cygwin-1.7 will again operate correctly under Wine. Until then, libtool will
6288 report warnings as described in @pxref{File Name Conversion Failure} in these
6291 However, @env{LT_CYGPATH} is also used for the MSYS to Cygwin cross compile
6292 scenario, and operates as expected.
6294 @node Cygwin to MinGW Cross
6295 @subsubsection Cygwin to MinGW Cross
6296 @cindex Cygwin to MinGW Cross
6298 There are actually three different scenarios that could all legitimately be
6299 called a ``Cygwin to MinGW'' cross compile. The current (and standard)
6300 definition is when there is a compiler that produces native Windows libraries
6301 and applications, but which itself is a Cygwin application, just as would be
6302 expected in any other cross compile setup.
6304 However, historically there were two other definitions, which we will refer
6305 to as the @emph{fake} one, and the @emph{lying} one.
6307 In the @emph{fake} Cygwin to MinGW cross compile case, you actually use a
6308 native MinGW compiler, but you do so from within a Cygwin environment:
6311 @kbd{export PATH="/c/MinGW/bin:$@{PATH@}"}
6312 @kbd{configure --build=i686-pc-cygwin \
6314 NM=/c/MinGW/bin/nm.exe}
6317 In this way, the build system ``knows'' that you are cross compiling, and the
6318 file name conversion logic will be used. However, because the tools
6319 (@command{mingw32-gcc}, @command{nm}, @command{ar}) used are actually native
6320 Windows applications, they will not understand any Cygwin (that is, Unix-like)
6321 absolute file names passed as command line arguments (and, unlike MSYS, Cygwin
6322 does not automatically convert such arguments). However, so long as only
6323 relative file names are used in the build system, and non-Windows-supported
6324 Unix idioms such as symlinks and mount points are avoided, this scenario should
6327 If you must use absolute file names, you will have to force Libtool to convert
6328 file names for the toolchain in this case, by doing the following before you
6332 @kbd{export lt_cv_to_tool_file_cmd=func_convert_file_cygwin_to_w32}
6334 @cindex lt_cv_to_tool_file_cmd
6335 @cindex func_convert_file_cygwin_to_w32
6337 In the @emph{lying} Cygwin to MinGW cross compile case, you lie to the
6341 @kbd{export PATH="/c/MinGW/bin:$@{PATH@}"}
6342 @kbd{configure --build=i686-pc-mingw32 \
6343 --host=i686-pc-mingw32 \
6344 --disable-dependency-tracking}
6348 and claim that the build platform is MinGW, even though you are actually
6349 running under @emph{Cygwin} and not MinGW. In this case, libtool does
6350 @emph{not} know that you are performing a cross compile, and thinks instead
6351 that you are performing a native MinGW build. However, as described in
6352 (@pxref{Native MinGW File Name Conversion}), that scenario triggers an ``MSYS
6353 to Windows'' file name conversion. This, of course, is the wrong conversion
6354 since we are actually running under Cygwin. Also, the toolchain is expecting
6355 Windows file names (not Cygwin) but unless told so Libtool will feed Cygwin
6356 file names to the toolchain in this case. To force the correct file name
6357 conversions in this situation, you should do the following @emph{before}
6361 @kbd{export lt_cv_to_host_file_cmd=func_convert_file_cygwin_to_w32}
6362 @kbd{export lt_cv_to_tool_file_cmd=func_convert_file_cygwin_to_w32}
6364 @cindex lt_cv_to_host_file_cmd
6365 @cindex lt_cv_to_tool_file_cmd
6366 @cindex func_convert_file_cygwin_to_w32
6368 Note that this relies on internal implementation details of libtool, and
6369 is subject to change. Also, @code{--disable-dependency-tracking} is required,
6370 because otherwise the MinGW GCC will generate dependency files that contain
6371 Windows file names. This, in turn, will confuse the Cygwin @command{make}
6372 program, which does not accept Windows file names:
6375 Makefile:1: *** target pattern contains no `%'. Stop.
6378 There have also always been a number of other details required for the
6379 @emph{lying} case to operate correctly, such as the use of so-called
6380 @dfn{identity mounts}:
6383 # @var{cygwin-root}/etc/fstab
6384 D:/foo /foo some_fs binary 0 0
6385 D:/bar /bar some_fs binary 0 0
6386 E:/grill /grill some_fs binary 0 0
6389 In this way, top-level directories of each drive are available using
6390 identical names within Cygwin.
6392 Note that you also need to ensure that the standard Unix directories
6393 (like @file{/bin}, @file{/lib}, @file{/usr}, @file{/etc}) appear in the root
6394 of a drive. This means that you must install Cygwin itself into the @file{C:/}
6395 root directory (or @file{D:/}, or @file{E:/}, etc)---instead of the
6396 recommended installation into @file{C:/cygwin/}. In addition, all file names
6397 used in the build system must be relative, symlinks should not be used within
6398 the source or build directory trees, and all @option{-M*} options to
6399 @command{gcc} except @option{-MMD} must be avoided.
6401 This is quite a fragile setup, but it has been in historical use, and so is
6405 @subsection Windows DLLs
6406 @cindex Windows DLLs
6408 This topic describes a couple of ways to portably create Windows Dynamic
6409 Link Libraries (DLLs). Libtool knows how to create DLLs using GNU tools
6410 and using Microsoft tools.
6412 A typical library has a ``hidden'' implementation with an interface
6413 described in a header file. On just about every system, the interface
6414 could be something like this:
6416 Example @file{foo.h}:
6430 And the implementation could be something like this:
6432 Example @file{foo.c}:
6444 return three - one ();
6450 When using contemporary GNU tools to create the Windows DLL, the above
6451 code will work there too, thanks to its auto-import/auto-export
6452 features. But that is not the case when using older GNU tools or perhaps
6453 more interestingly when using proprietary tools. In those cases the code
6454 will need additional decorations on the interface symbols with
6455 @code{__declspec(dllimport)} and @code{__declspec(dllexport)} depending
6456 on whether the library is built or it's consumed and how it's built and
6457 consumed. However, it should be noted that it would have worked also
6458 with Microsoft tools, if only the variable @code{three} hadn't been
6459 there, due to the fact the Microsoft tools will automatically import
6460 functions (but sadly not variables) and Libtool will automatically export
6461 non-static symbols as described next.
6463 With Microsoft tools, Libtool digs through the object files that make up
6464 the library, looking for non-static symbols to automatically export.
6465 I.e., Libtool with Microsoft tools tries to mimic the auto-export feature
6466 of contemporary GNU tools. It should be noted that the GNU auto-export
6467 feature is turned off when an explicit @code{__declspec(dllexport)} is
6468 seen. The GNU tools do this to not make more symbols visible for projects
6469 that have already taken the trouble to decorate symbols. There is no
6470 similar way to limit which symbols are visible in the code when Libtool
6471 is using Microsoft tools. In order to limit symbol visibility in that
6472 case you need to use one of the options @option{-export-symbols} or
6473 @option{-export-symbols-regex}.
6475 No matching help with auto-import is provided by Libtool, which is why
6476 variables must be decorated to import them from a DLL for everything but
6477 contemporary GNU tools. As stated above, functions are automatically
6478 imported by both contemporary GNU tools and Microsoft tools, but for
6479 other proprietary tools the auto-import status of functions is unknown.
6481 When the objects that form the library are built, there are generally
6482 two copies built for each object. One copy is used when linking the DLL
6483 and one copy is used for the static library. On Windows systems, a pair
6484 of defines are commonly used to discriminate how the interface symbols
6485 should be decorated. The first define is @samp{-DDLL_EXPORT} which is
6486 automatically provided by Libtool when @command{libtool} builds the copy
6487 of the object that is destined for the DLL. The second define is
6488 @samp{-DLIBFOO_BUILD} (or similar) which is often added by the package
6489 providing the library and is used when building the library, but not
6490 when consuming the library.
6492 However, the matching double compile is not performed when consuming
6493 libraries. It is therefore not possible to reliably distinguish if the
6494 consumer is importing from a DLL or if it is going to use a static
6497 With contemporary GNU tools, auto-import often saves the day, but see
6498 the GNU ld documentation and its @option{--enable-auto-import} option
6499 for some corner cases when it does not
6500 (@pxref{Options, @option{--enable-auto-import}, Options specific to
6501 i386 PE targets, ld, Using ld@comma{} the GNU linker}).
6503 With Microsoft tools you typically get away with always compiling the
6504 code such that variables are expected to be imported from a DLL and
6505 functions are expected to be found in a static library. The tools will
6506 then automatically import the function from a DLL if that is where they
6507 are found. If the variables are not imported from a DLL as expected, but
6508 are found in a static library that is otherwise pulled in by some
6509 function, the linker will issue a warning (LNK4217) that a locally
6510 defined symbol is imported, but it still works. In other words, this
6511 scheme will not work to only consume variables from a library. There is
6512 also a price connected to this liberal use of imports in that an extra
6513 indirection is introduced when you are consuming the static version of
6514 the library. That extra indirection is unavoidable when the DLL is
6515 consumed, but it is not needed when consuming the static library.
6517 For older GNU tools and other proprietary tools there is no generic way
6518 to make it possible to consume either of the DLL or the static library
6519 without user intervention, the tools need to be told what is intended.
6520 One common assumption is that if a DLL is being built (@samp{DLL_EXPORT}
6521 is defined) then that DLL is going to consume any dependent libraries as
6522 DLLs. If that assumption is made everywhere, it is possible to select
6523 how an end-user application is consuming libraries by adding a single
6524 flag @samp{-DDLL_EXPORT} when a DLL build is required. This is of course
6525 an all or nothing deal, either everything as DLLs or everything as static
6528 To sum up the above, the header file of the foo library needs to be
6529 changed into something like this:
6531 Modified @file{foo.h}:
6537 #if defined _WIN32 && !defined __GNUC__
6538 # ifdef LIBFOO_BUILD
6540 # define LIBFOO_SCOPE __declspec (dllexport)
6541 # define LIBFOO_SCOPE_VAR extern __declspec (dllexport)
6543 # elif defined _MSC_VER
6544 # define LIBFOO_SCOPE
6545 # define LIBFOO_SCOPE_VAR extern __declspec (dllimport)
6546 # elif defined DLL_EXPORT
6547 # define LIBFOO_SCOPE __declspec (dllimport)
6548 # define LIBFOO_SCOPE_VAR extern __declspec (dllimport)
6551 #ifndef LIBFOO_SCOPE
6552 # define LIBFOO_SCOPE
6553 # define LIBFOO_SCOPE_VAR extern
6556 LIBFOO_SCOPE int one (void);
6557 LIBFOO_SCOPE int two (void);
6558 LIBFOO_SCOPE_VAR int three;
6563 When the targets are limited to contemporary GNU tools and Microsoft
6564 tools, the above can be simplified to the following:
6566 Simplified @file{foo.h}:
6572 #if defined _WIN32 && !defined __GNUC__ && !defined LIBFOO_BUILD
6573 # define LIBFOO_SCOPE_VAR extern __declspec (dllimport)
6575 # define LIBFOO_SCOPE_VAR extern
6580 LIBFOO_SCOPE_VAR int three;
6585 This last simplified version can of course only work when Libtool is
6586 used to build the DLL, as no symbols would be exported otherwise (i.e.,
6587 when using Microsoft tools).
6589 It should be noted that there are various projects that attempt to relax
6590 these requirements by various low level tricks, but they are not
6593 @uref{http://alain.frisch.fr/@/flexdll.html, FlexDLL} and
6594 @uref{http://edll.sourceforge.net/, edll}.
6597 @node libtool script contents
6598 @section @code{libtool} script contents
6599 @cindex implementation of libtool
6600 @cindex libtool implementation
6602 Since version 1.4, the @code{libtool} script is generated by
6603 @code{configure} (@pxref{Configuring}). In earlier versions,
6604 @code{configure} achieved this by calling a helper script called
6605 @file{ltconfig}. From libtool version 0.7 to 1.0, this script
6606 simply set shell variables, then sourced the libtool backend,
6607 @code{ltmain.sh}. @code{ltconfig} from libtool version 1.1 through 1.3
6608 inlined the contents of @code{ltmain.sh} into the generated
6609 @code{libtool}, which improved performance on many systems. The tests
6610 that @file{ltconfig} used to perform are now kept in @file{libtool.m4}
6611 where they can be written using Autoconf. This has the runtime
6612 performance benefits of inlined @code{ltmain.sh}, @emph{and} improves
6613 the build time a little while considerably easing the amount of raw
6614 shell code that used to need maintaining.
6616 The convention used for naming variables that hold shell commands for
6617 delayed evaluation, is to use the suffix @code{_cmd} where a single
6618 line of valid shell script is needed, and the suffix @code{_cmds} where
6619 multiple lines of shell script @strong{may} be delayed for later
6620 evaluation. By convention, @code{_cmds} variables delimit the
6621 evaluation units with the @code{~} character where necessary.
6623 Here is a listing of each of the configuration variables, and how they
6624 are used within @code{ltmain.sh} (@pxref{Configuring}):
6627 The name of the system library archiver.
6631 The name of the compiler used to configure libtool. This will always
6632 contain the compiler for the current language (@pxref{Tags}).
6636 An @command{echo} program that does not interpret backslashes as an
6637 escape character. It may be given only one argument, so due quoting
6642 The name of the linker that libtool should use internally for reloadable
6643 linking and possibly shared libraries.
6648 The name of the C compiler and C compiler flags used to configure
6653 The name of a BSD- or MS-compatible program that produces listings of
6655 For BSD @command{nm}, the symbols should be in one the following formats:
6658 @var{address} C @var{global-variable-name}
6659 @var{address} D @var{global-variable-name}
6660 @var{address} T @var{global-function-name}
6663 For MS @command{dumpbin}, the symbols should be in one of the following
6667 @var{counter} @var{size} UNDEF notype External | @var{global-var}
6668 @var{counter} @var{address} @var{section} notype External | @var{global-var}
6669 @var{counter} @var{address} @var{section} notype () External | @var{global-func}
6672 The @var{size} of the global variables are not zero and the @var{section}
6673 of the global functions are not "UNDEF". Symbols in "pick any" sections
6674 ("pick any" appears in the section header) are not global either.
6678 Set to the name of the @command{ranlib} program, if any.
6681 @defvar allow_undefined_flag
6682 The flag that is used by @samp{archive_cmds} in order to declare that
6683 there will be unresolved symbols in the resulting shared library.
6684 Empty, if no such flag is required. Set to @samp{unsupported} if there
6685 is no way to generate a shared library with references to symbols that
6686 aren't defined in that library.
6689 @defvar always_export_symbols
6690 Whether libtool should automatically generate a list of exported symbols
6691 using @code{export_symbols_cmds} before linking an archive.
6692 Set to @samp{yes} or @samp{no}. Default is @samp{no}.
6695 @defvar archive_cmds
6696 @defvarx archive_expsym_cmds
6697 @defvarx old_archive_cmds
6698 Commands used to create shared libraries, shared libraries with
6699 @option{-export-symbols} and static libraries, respectively.
6702 @defvar archiver_list_spec
6703 Specify filename containing input files for @code{AR}.
6706 @defvar old_archive_from_new_cmds
6707 If the shared library depends on a static library,
6708 @samp{old_archive_from_new_cmds} contains the commands used to create that
6709 static library. If this variable is not empty, @samp{old_archive_cmds} is
6713 @defvar old_archive_from_expsyms_cmds
6714 If a static library must be created from the export symbol list in order to
6715 correctly link with a shared library, @samp{old_archive_from_expsyms_cmds}
6716 contains the commands needed to create that static library. When these
6717 commands are executed, the variable @code{soname} contains the name of the
6718 shared library in question, and the @samp{$objdir/$newlib} contains the
6719 path of the static library these commands should build. After executing
6720 these commands, libtool will proceed to link against @samp{$objdir/$newlib}
6721 instead of @code{soname}.
6724 @defvar lock_old_archive_extraction
6725 Set to @samp{yes} if the extraction of a static library requires locking
6726 the library file. This is required on Darwin.
6730 @defvarx build_alias
6732 Set to the specified and canonical names of the system that libtool was
6736 @defvar build_libtool_libs
6737 Whether libtool should build shared libraries on this system. Set to
6738 @samp{yes} or @samp{no}.
6741 @defvar build_old_libs
6742 Whether libtool should build static libraries on this system. Set to
6743 @samp{yes} or @samp{no}.
6746 @defvar compiler_c_o
6747 Whether the compiler supports the @option{-c} and @option{-o} options
6748 simultaneously. Set to @samp{yes} or @samp{no}.
6751 @defvar compiler_needs_object
6752 Whether the compiler has to see an object listed on the command line in
6753 order to successfully invoke the linker. If @samp{no}, then a set of
6754 convenience archives or a set of object file names can be passed via
6755 linker-specific options or linker scripts.
6758 @defvar dlopen_support
6759 Whether @code{dlopen} is supported on the platform.
6760 Set to @samp{yes} or @samp{no}.
6764 Whether it is possible to @code{dlopen} the executable itself.
6765 Set to @samp{yes} or @samp{no}.
6768 @defvar dlopen_self_static
6769 Whether it is possible to @code{dlopen} the executable itself, when it
6770 is linked statically (@option{-all-static}). Set to @samp{yes} or
6774 @defvar exclude_expsyms
6775 List of symbols that should not be listed in the preloaded symbols.
6778 @defvar export_dynamic_flag_spec
6779 Compiler link flag that allows a dlopened shared library to reference
6780 symbols that are defined in the program.
6783 @defvar export_symbols_cmds
6784 Commands to extract exported symbols from @code{libobjs} to the
6785 file @code{export_symbols}.
6788 @defvar extract_expsyms_cmds
6789 Commands to extract the exported symbols list from a shared library.
6790 These commands are executed if there is no file @samp{$objdir/$soname-def},
6791 and should write the names of the exported symbols to that file, for
6792 the use of @samp{old_archive_from_expsyms_cmds}.
6795 @defvar fast_install
6796 Determines whether libtool will privilege the installer or the
6797 developer. The assumption is that installers will seldom run programs
6798 in the build tree, and the developer will seldom install. This is only
6799 meaningful on platforms where @code{shlibpath_overrides_runpath} is
6800 not @samp{yes}, so @code{fast_install} will be set to @samp{needless} in
6801 this case. If @code{fast_install} set to @samp{yes}, libtool will create
6802 programs that search for installed libraries, and, if a program is run
6803 in the build tree, a new copy will be linked on-demand to use the
6804 yet-to-be-installed libraries. If set to @samp{no}, libtool will create
6805 programs that use the yet-to-be-installed libraries, and will link
6806 a new copy of the program at install time. The default value is
6807 @samp{yes} or @samp{needless}, depending on platform and configuration
6808 flags, and it can be turned from @samp{yes} to @samp{no} with the
6809 configure flag @option{--disable-fast-install}.
6811 On some systems, the linker always hardcodes paths to dependent libraries
6812 into the output. In this case, @code{fast_install} is never set to @samp{yes},
6813 and relinking at install time is triggered. This also means that @env{DESTDIR}
6814 installation does not work as expected.
6817 @defvar file_magic_glob
6818 How to find potential files when @code{deplibs_check_method} is
6819 @samp{file_magic}. @code{file_magic_glob} is a @code{sed} expression,
6820 and the @code{sed} instance is fed potential file names that are
6821 transformed by the @code{file_magic_glob} expression. Useful when the
6822 shell does not support the shell option @code{nocaseglob}, making
6823 @code{want_nocaseglob} inappropriate. Normally disabled (i.e.
6824 @code{file_magic_glob} is empty).
6828 Commands to tell the dynamic linker how to find shared libraries in a
6833 Same as @code{finish_cmds}, except the commands are not displayed.
6836 @defvar global_symbol_pipe
6837 A pipeline that takes the output of @code{NM}, and produces a listing of
6838 raw symbols followed by their C names. For example:
6841 $ @kbd{eval "$NM progname | $global_symbol_pipe"}
6842 D @var{symbol1} @var{C-symbol1}
6843 T @var{symbol2} @var{C-symbol2}
6844 C @var{symbol3} @var{C-symbol3}
6849 The first column contains the symbol type (used to tell data from code)
6850 but its meaning is system dependent.
6853 @defvar global_symbol_to_cdecl
6854 A pipeline that translates the output of @code{global_symbol_pipe} into
6855 proper C declarations. Since some platforms, such as HP/UX, have
6856 linkers that differentiate code from data, data symbols are declared
6857 as data, and code symbols are declared as functions.
6860 @defvar hardcode_action
6861 Either @samp{immediate} or @samp{relink}, depending on whether shared
6862 library paths can be hardcoded into executables before they are installed,
6863 or if they need to be relinked.
6866 @defvar hardcode_direct
6867 Set to @samp{yes} or @samp{no}, depending on whether the linker
6868 hardcodes directories if a library is directly specified on the command
6869 line (such as @samp{@var{dir}/lib@var{name}.a}) when
6870 @code{hardcode_libdir_flag_spec} is specified.
6873 @defvar hardcode_direct_absolute
6874 Some architectures hardcode "absolute" library directories that can not
6875 be overridden by @code{shlibpath_var} when @code{hardcode_direct} is
6876 @samp{yes}. In that case set @code{hardcode_direct_absolute} to
6877 @samp{yes}, or otherwise @samp{no}.
6880 @defvar hardcode_into_libs
6881 Whether the platform supports hardcoding of run-paths into libraries.
6882 If enabled, linking of programs will be much simpler but libraries will
6883 need to be relinked during installation. Set to @samp{yes} or @samp{no}.
6886 @defvar hardcode_libdir_flag_spec
6887 Flag to hardcode a @code{libdir} variable into a binary, so that the
6888 dynamic linker searches @code{libdir} for shared libraries at runtime.
6889 If it is empty, libtool will try to use some other hardcoding mechanism.
6892 @defvar hardcode_libdir_separator
6893 If the compiler only accepts a single @code{hardcode_libdir_flag}, then
6894 this variable contains the string that should separate multiple
6895 arguments to that flag.
6898 @defvar hardcode_minus_L
6899 Set to @samp{yes} or @samp{no}, depending on whether the linker
6900 hardcodes directories specified by @option{-L} flags into the resulting
6901 executable when @code{hardcode_libdir_flag_spec} is specified.
6904 @defvar hardcode_shlibpath_var
6905 Set to @samp{yes} or @samp{no}, depending on whether the linker
6906 hardcodes directories by writing the contents of @samp{$shlibpath_var}
6907 into the resulting executable when @code{hardcode_libdir_flag_spec} is
6908 specified. Set to @samp{unsupported} if directories specified by
6909 @samp{$shlibpath_var} are searched at run time, but not at link time.
6915 Set to the specified and canonical names of the system that libtool was
6919 @defvar include_expsyms
6920 List of symbols that must always be exported when using @code{export_symbols}.
6923 @defvar inherit_rpath
6924 Whether the linker adds runtime paths of dependency libraries to the
6925 runtime path list, requiring libtool to relink the output when installing.
6926 Set to @samp{yes} or @samp{no}. Default is @samp{no}.
6929 @defvar install_override_mode
6930 Permission mode override for installation of shared libraries. If the
6931 runtime linker fails to load libraries with wrong permissions, then it
6932 may fail to execute programs that are needed during installation,
6933 because these need the library that has just been installed. In this
6934 case, it is necessary to pass the mode to @command{install} with
6935 @option{-m @var{install_override_mode}}.
6939 The standard old archive suffix (normally @samp{a}).
6942 @defvar libname_spec
6943 The format of a library name prefix. On all Unix systems, static
6944 libraries are called @samp{lib@var{name}.a}, but on some systems (such
6945 as OS/2 or MS-DOS), the library is just called @samp{@var{name}.a}.
6948 @defvar library_names_spec
6949 A list of shared library names. The first is the name of the file,
6950 the rest are symbolic links to the file. The name in the list is
6951 the file name that the linker finds when given @option{-l@var{name}}.
6954 @defvar link_all_deplibs
6955 Whether libtool must link a program against all its dependency libraries.
6956 Set to @samp{yes} or @samp{no}. Default is @samp{unknown}, which is
6957 a synonym for @samp{yes}.
6960 @defvar link_static_flag
6961 Linker flag (passed through the C compiler) used to prevent dynamic
6965 @defvar macro_version
6966 @defvarx macro_revision
6967 The release and revision from which the libtool.m4 macros were
6968 taken. This is used to ensure that macros and @code{ltmain.sh}
6969 correspond to the same Libtool version.
6973 The approximate longest command line that can be passed to @samp{$SHELL}
6974 without being truncated, as computed by @samp{LT_CMD_MAX_LEN}.
6977 @defvar need_lib_prefix
6978 Whether we can @code{dlopen} modules without a @samp{lib} prefix.
6979 Set to @samp{yes} or @samp{no}. By default, it is @samp{unknown}, which
6980 means the same as @samp{yes}, but documents that we are not really sure
6981 about it. @samp{no} means that it is possible to @code{dlopen} a
6982 module without the @samp{lib} prefix.
6985 @defvar need_version
6986 Whether versioning is required for libraries, i.e.@: whether the
6987 dynamic linker requires a version suffix for all libraries.
6988 Set to @samp{yes} or @samp{no}. By default, it is @samp{unknown}, which
6989 means the same as @samp{yes}, but documents that we are not really sure
6994 Whether files must be locked to prevent conflicts when compiling
6995 simultaneously. Set to @samp{yes} or @samp{no}.
6998 @defvar nm_file_list_spec
6999 Specify filename containing input files for @code{NM}.
7002 @defvar no_builtin_flag
7003 Compiler flag to disable builtin functions that conflict with declaring
7004 external global symbols as @code{char}.
7007 @defvar no_undefined_flag
7008 The flag that is used by @samp{archive_cmds} in order to declare that
7009 there will be no unresolved symbols in the resulting shared library.
7010 Empty, if no such flag is required.
7014 The name of the directory that contains temporary libtool files.
7018 The standard object file suffix (normally @samp{o}).
7022 Any additional compiler flags for building library object files.
7025 @defvar postinstall_cmds
7026 @defvarx old_postinstall_cmds
7027 Commands run after installing a shared or static library, respectively.
7030 @defvar postuninstall_cmds
7031 @defvarx old_postuninstall_cmds
7032 Commands run after uninstalling a shared or static library, respectively.
7035 @defvar postlink_cmds
7036 Commands necessary for finishing linking programs. @code{postlink_cmds}
7037 are executed immediately after the program is linked. Any occurrence of
7038 the string @code{@@OUTPUT@@} in @code{postlink_cmds} is replaced by the
7039 name of the created executable (i.e.@: not the wrapper, if a wrapper is
7040 generated) prior to execution. Similarly, @code{@@TOOL_OUTPUT@@} is
7041 replaced by the toolchain format of @code{@@OUTPUT@@}. Normally disabled
7042 (i.e.@: @code{postlink_cmds} empty).
7046 @defvarx reload_flag
7047 Commands to create a reloadable object. Set @code{reload_cmds} to
7048 @samp{false} on systems that cannot create reloadable objects.
7052 The environment variable that tells the linker which directories to
7053 hardcode in the resulting executable.
7056 @defvar shlibpath_overrides_runpath
7057 Indicates whether it is possible to override the hard-coded library
7058 search path of a program with an environment variable. If this is set
7059 to no, libtool may have to create two copies of a program in the build
7060 tree, one to be installed and one to be run in the build tree only.
7061 When each of these copies is created depends on the value of
7062 @code{fast_install}. The default value is @samp{unknown}, which is
7063 equivalent to @samp{no}.
7066 @defvar shlibpath_var
7067 The environment variable that tells the dynamic linker where to find
7072 The name coded into shared libraries, if different from the real name of
7077 @defvarx old_striplib
7078 Command to strip a shared (@code{striplib}) or static (@code{old_striplib})
7079 library, respectively. If these variables are empty, the strip flag
7080 in the install mode will be ignored for libraries (@pxref{Install mode}).
7083 @defvar sys_lib_dlsearch_path_spec
7084 Expression to get the run-time system library search path. Directories
7085 that appear in this list are never hard-coded into executables.
7088 @defvar sys_lib_search_path_spec
7089 Expression to get the compile-time system library search path. This
7090 variable is used by libtool when it has to test whether a certain
7091 library is shared or static. The directories listed in
7092 @code{shlibpath_var} are automatically appended to this list, every time
7093 libtool runs (i.e., not at configuration time), because some linkers use
7094 this variable to extend the library search path. Linker switches such
7095 as @option{-L} also augment the search path.
7098 @defvar thread_safe_flag_spec
7099 Linker flag (passed through the C compiler) used to generate thread-safe
7103 @defvar to_host_file_cmd
7104 If the toolchain is not native to the build platform (e.g.@: if you are using
7105 MSYS to drive the scripting, but are using the MinGW native Windows compiler)
7106 this variable describes how to convert file names from the format used by the
7107 build platform to the format used by host platform. Normally set to
7108 @samp{func_convert_file_noop}, libtool will autodetect most cases in which
7109 other values should be used. On rare occasions, it may be necessary to override
7110 the autodetected value (@pxref{Cygwin to MinGW Cross}).
7113 @defvar to_tool_file_cmd
7114 If the toolchain is not native to the build platform (e.g.@: if you are using
7115 some Unix to drive the scripting together with a Windows toolchain running
7116 in Wine) this variable describes how to convert file names from the format
7117 used by the build platform to the format used by the toolchain. Normally set
7118 to @samp{func_convert_file_noop}.
7121 @defvar version_type
7122 The library version numbering type. One of @samp{libtool},
7123 @samp{freebsd-aout}, @samp{freebsd-elf}, @samp{irix}, @samp{linux},
7124 @samp{osf}, @samp{sunos}, @samp{windows}, or @samp{none}.
7127 @defvar want_nocaseglob
7128 Find potential files using the shell option @code{nocaseglob}, when
7129 @code{deplibs_check_method} is @samp{file_magic}. Normally set to
7130 @samp{no}. Set to @samp{yes} to enable the @code{nocaseglob} shell
7131 option when looking for potential file names in a case-insensitive
7135 @defvar whole_archive_flag_spec
7136 Compiler flag to generate shared objects from convenience archives.
7140 The C compiler flag that allows libtool to pass a flag directly to the
7141 linker. Used as: @code{$@{wl@}@var{some-flag}}.
7144 Variables ending in @samp{_cmds} or @samp{_eval} contain a
7145 @samp{~}-separated list of commands that are @code{eval}ed one after
7146 another. If any of the commands return a nonzero exit status, libtool
7147 generally exits with an error message.
7149 Variables ending in @samp{_spec} are @code{eval}ed before being used by
7153 @section Cheap tricks
7155 Here are a few tricks that you can use in order to make maintainership
7160 When people report bugs, ask them to use the @option{--config},
7161 @option{--debug}, or @option{--features} flags, if you think they will help
7162 you. These flags are there to help you get information directly, rather
7163 than having to trust second-hand observation.
7166 Rather than reconfiguring libtool every time I make a change to
7167 @code{ltmain.in}, I keep a permanent @code{libtool} script in my
7168 @env{PATH}, which sources @code{ltmain.in} directly.
7170 The following steps describe how to create such a script, where
7171 @code{/home/src/libtool} is the directory containing the libtool source
7172 tree, @code{/home/src/libtool/libtool} is a libtool script that has been
7173 configured for your platform, and @code{~/bin} is a directory in your
7178 trick$ sed 's%^\(macro_version=\).*$%\1@@VERSION@@%;
7179 s%^\(macro_revision=\).*$%\1@@package_revision@@%;
7180 /^# ltmain\.sh/q' /home/src/libtool/libtool > libtool
7181 trick$ echo '. /home/src/libtool/ltmain.in' >> libtool
7182 trick$ chmod +x libtool
7183 trick$ libtool --version
7184 ltmain.sh (GNU @@PACKAGE@@@@TIMESTAMP@@) @@VERSION@@
7186 Copyright (C) 2011 Free Software Foundation, Inc.
7187 This is free software; see the source for copying conditions. There is NO
7188 warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
7193 The output of the final @samp{libtool --version} command shows that the
7194 @code{ltmain.in} script is being used directly. Now, modify
7195 @code{~/bin/libtool} or @code{/home/src/libtool/ltmain.in} directly in
7196 order to test new changes without having to rerun @code{configure}.
7198 @node GNU Free Documentation License
7199 @appendix GNU Free Documentation License
7201 @cindex FDL, GNU Free Documentation License
7206 @node Combined Index
7207 @unnumbered Combined Index