1 This is ../doc/libtool.info, produced by makeinfo version 4.13 from
4 INFO-DIR-SECTION GNU programming tools
6 * Libtool: (libtool). Generic shared library support script.
9 INFO-DIR-SECTION Individual utilities
11 * libtool-invocation: (libtool)Invoking libtool.
12 Running the `libtool' script.
13 * libtoolize: (libtool)Invoking libtoolize. Adding libtool support.
16 This file documents GNU Libtool 2.2.10
18 Copyright (C) 1996-2009 Free Software Foundation, Inc.
20 Permission is granted to copy, distribute and/or modify this document
21 under the terms of the GNU Free Documentation License, Version 1.3 or
22 any later version published by the Free Software Foundation; with no
23 Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
24 Texts. A copy of the license is included in the section entitled "GNU
25 Free Documentation License".
28 File: libtool.info, Node: Top, Next: Introduction, Prev: (dir), Up: (dir)
30 Shared library support for GNU
31 ******************************
33 This file documents GNU Libtool, a script that allows package developers
34 to provide generic shared library support. This edition documents
37 *Note Reporting bugs::, for information on how to report problems
42 * Introduction:: What the heck is libtool?
43 * Libtool paradigm:: How libtool's view of libraries is different.
44 * Using libtool:: Example of using libtool to build libraries.
45 * Invoking libtool:: Running the `libtool' script.
46 * Integrating libtool:: Using libtool in your own packages.
47 * Other languages:: Using libtool without a C compiler.
48 * Versioning:: Using library interface versions.
49 * Library tips:: Tips for library interface design.
50 * Inter-library dependencies:: Libraries that depend on other libraries.
51 * Dlopened modules:: `dlopen'ing libtool-created libraries.
52 * Using libltdl:: Libtool's portable `dlopen' wrapper library.
53 * Trace interface:: Libtool's trace interface.
54 * FAQ:: Frequently Asked Questions
55 * Troubleshooting:: When libtool doesn't work as advertised.
56 * Maintaining:: Information used by the libtool maintainer.
57 * GNU Free Documentation License:: License for this manual.
60 --- The Detailed Node Listing ---
64 * Motivation:: Why does GNU need a libtool?
65 * Issues:: The problems that need to be addressed.
66 * Other implementations:: How other people have solved these issues.
67 * Postmortem:: Learning from past difficulties.
71 * Creating object files:: Compiling object files for libraries.
72 * Linking libraries:: Creating libraries from object files.
73 * Linking executables:: Linking object files against libtool libraries.
74 * Debugging executables:: Running GDB on libtool-generated programs.
75 * Installing libraries:: Making libraries available to users.
76 * Installing executables:: Making programs available to users.
77 * Static libraries:: When shared libraries are not wanted.
81 * Wrapper executables:: Wrapper executables for some platforms.
85 * Compile mode:: Creating library object files.
86 * Link mode:: Generating executables and libraries.
87 * Execute mode:: Debugging libtool-generated programs.
88 * Install mode:: Making libraries and executables public.
89 * Finish mode:: Completing a library installation.
90 * Uninstall mode:: Removing installed executables and libraries.
91 * Clean mode:: Removing uninstalled executables and libraries.
93 Integrating libtool with your package
95 * Autoconf macros:: Autoconf macros exported by libtool.
96 * Makefile rules:: Writing `Makefile' rules for libtool.
97 * Using Automake:: Automatically supporting libtool.
98 * Configuring:: Configuring libtool for a host system.
99 * Distributing:: What files to distribute with your package.
100 * Static-only libraries:: Sometimes shared libraries are just a pain.
104 * LT_INIT:: Configuring `libtool' in `configure.ac'.
105 * Configure notes:: Platform-specific notes for configuration.
107 Including libtool in your package
109 * Invoking libtoolize:: `libtoolize' command line options.
110 * Autoconf and LTLIBOBJS:: Autoconf automates LTLIBOBJS generation.
112 Using libtool with other languages
114 * C++ libraries:: Writing libraries for C++
117 Library interface versions
119 * Interfaces:: What are library interfaces?
120 * Libtool versioning:: Libtool's versioning system.
121 * Updating version info:: Changing version information before releases.
122 * Release numbers:: Breaking binary compatibility for aesthetics.
124 Tips for interface design
126 * C header files:: How to write portable include files.
130 * Building modules:: Creating dlopenable objects and libraries.
131 * Dlpreopening:: Dlopening that works on static platforms.
132 * Linking with dlopened modules:: Using dlopenable modules in libraries.
133 * Finding the dlname:: Choosing the right file to `dlopen'.
134 * Dlopen issues:: Unresolved problems that need your attention.
138 * Libltdl interface:: How to use libltdl in your programs.
139 * Modules for libltdl:: Creating modules that can be `dlopen'ed.
140 * Thread Safety in libltdl:: Registering callbacks for multi-thread safety.
141 * User defined module data:: Associating data with loaded modules.
142 * Module loaders for libltdl:: Creating user defined module loaders.
143 * Distributing libltdl:: How to distribute libltdl with your package.
145 Frequently Asked Questions
147 * Stripped link flags:: Dropped flags when creating a library
151 * Libtool test suite:: Libtool's self-tests.
152 * Reporting bugs:: How to report problems with libtool.
154 The libtool test suite
156 * Test descriptions:: The contents of the test suite.
157 * When tests fail:: What to do when a test fails.
159 Maintenance notes for libtool
161 * New ports:: How to port libtool to new systems.
162 * Tested platforms:: When libtool was last tested.
163 * Platform quirks:: Information about different library systems.
164 * libtool script contents:: Configuration information that libtool uses.
165 * Cheap tricks:: Making libtool maintainership easier.
167 Porting libtool to new systems
169 * Information sources:: Where to find relevant documentation
170 * Porting inter-library dependencies:: Implementation details explained
174 * References:: Finding more information.
175 * Compilers:: Creating object files from source files.
176 * Reloadable objects:: Binding object files together.
177 * Multiple dependencies:: Removing duplicate dependent libraries.
178 * Archivers:: Programs that create static archives.
181 File: libtool.info, Node: Introduction, Next: Libtool paradigm, Prev: Top, Up: Top
186 In the past, if you were a source code package developer and wanted to
187 take advantage of the power of shared libraries, you needed to write
188 custom support code for each platform on which your package ran. You
189 also had to design a configuration interface so that the package
190 installer could choose what sort of libraries were built.
192 GNU Libtool simplifies your job by encapsulating both the
193 platform-specific dependencies, and the user interface, in a single
194 script. GNU Libtool is designed so that the complete functionality of
195 each host type is available via a generic interface, but nasty quirks
196 are hidden from the programmer.
198 GNU Libtool's consistent interface is reassuring... users don't need
199 to read obscure documentation in order to have their favorite source
200 package build shared libraries. They just run your package `configure'
201 script (or equivalent), and libtool does all the dirty work.
203 There are several examples throughout this document. All assume the
204 same environment: we want to build a library, `libhello', in a generic
207 `libhello' could be a shared library, a static library, or both...
208 whatever is available on the host system, as long as libtool has been
211 This chapter explains the original design philosophy of libtool.
212 Feel free to skip to the next chapter, unless you are interested in
213 history, or want to write code to extend libtool in a consistent way.
217 * Motivation:: Why does GNU need a libtool?
218 * Issues:: The problems that need to be addressed.
219 * Other implementations:: How other people have solved these issues.
220 * Postmortem:: Learning from past difficulties.
223 File: libtool.info, Node: Motivation, Next: Issues, Up: Introduction
225 1.1 Motivation for writing libtool
226 ==================================
228 Since early 1995, several different GNU developers have recognized the
229 importance of having shared library support for their packages. The
230 primary motivation for such a change is to encourage modularity and
231 reuse of code (both conceptually and physically) in GNU programs.
233 Such a demand means that the way libraries are built in GNU packages
234 needs to be general, to allow for any library type the package installer
235 might want. The problem is compounded by the absence of a standard
236 procedure for creating shared libraries on different platforms.
238 The following sections outline the major issues facing shared library
239 support in GNU, and how shared library support could be standardized
242 The following specifications were used in developing and evaluating
245 1. The system must be as elegant as possible.
247 2. The system must be fully integrated with the GNU Autoconf and
248 Automake utilities, so that it will be easy for GNU maintainers to
249 use. However, the system must not require these tools, so that it
250 can be used by non-GNU packages.
252 3. Portability to other (non-GNU) architectures and tools is
256 File: libtool.info, Node: Issues, Next: Other implementations, Prev: Motivation, Up: Introduction
258 1.2 Implementation issues
259 =========================
261 The following issues need to be addressed in any reusable shared library
262 system, specifically libtool:
264 1. The package installer should be able to control what sort of
267 2. It can be tricky to run dynamically linked programs whose
268 libraries have not yet been installed. `LD_LIBRARY_PATH' must be
269 set properly (if it is supported), or programs fail to run.
271 3. The system must operate consistently even on hosts that don't
272 support shared libraries.
274 4. The commands required to build shared libraries may differ wildly
275 from host to host. These need to be determined at configure time
278 5. It is not always obvious with what prefix or suffix a shared
279 library should be installed. This makes it difficult for
280 `Makefile' rules, since they generally assume that file names are
281 the same from host to host.
283 6. The system needs a simple library version number abstraction, so
284 that shared libraries can be upgraded in place. The programmer
285 should be informed how to design the interfaces to the library to
286 maximize binary compatibility.
288 7. The install `Makefile' target should warn the package installer to
289 set the proper environment variables (`LD_LIBRARY_PATH' or
290 equivalent), or run `ldconfig'.
293 File: libtool.info, Node: Other implementations, Next: Postmortem, Prev: Issues, Up: Introduction
295 1.3 Other implementations
296 =========================
298 Even before libtool was developed, many free software packages built and
299 installed their own shared libraries. At first, these packages were
300 examined to avoid reinventing existing features.
302 Now it is clear that none of these packages have documented the
303 details of shared library systems that libtool requires. So, other
304 packages have been more or less abandoned as influences.
307 File: libtool.info, Node: Postmortem, Prev: Other implementations, Up: Introduction
309 1.4 A postmortem analysis of other implementations
310 ==================================================
312 In all fairness, each of the implementations that were examined do the
313 job that they were intended to do, for a number of different host
314 systems. However, none of these solutions seem to function well as a
315 generalized, reusable component.
317 Most were too complex to use (much less modify) without understanding
318 exactly what the implementation does, and they were generally not
321 The main difficulty is that different vendors have different views of
322 what libraries are, and none of the packages that were examined seemed
323 to be confident enough to settle on a single paradigm that just _works_.
325 Ideally, libtool would be a standard that would be implemented as
326 series of extensions and modifications to existing library systems to
327 make them work consistently. However, it is not an easy task to
328 convince operating system developers to mend their evil ways, and
329 people want to build shared libraries right now, even on buggy, broken,
330 confused operating systems.
332 For this reason, libtool was designed as an independent shell script.
333 It isolates the problems and inconsistencies in library building that
334 plague `Makefile' writers by wrapping the compiler suite on different
335 platforms with a consistent, powerful interface.
337 With luck, libtool will be useful to and used by the GNU community,
338 and that the lessons that were learned in writing it will be taken up by
339 designers of future library systems.
342 File: libtool.info, Node: Libtool paradigm, Next: Using libtool, Prev: Introduction, Up: Top
344 2 The libtool paradigm
345 **********************
347 At first, libtool was designed to support an arbitrary number of library
348 object types. After libtool was ported to more platforms, a new
349 paradigm gradually developed for describing the relationship between
350 libraries and programs.
352 In summary, "libraries are programs with multiple entry points, and
353 more formally defined interfaces."
355 Version 0.7 of libtool was a complete redesign and rewrite of
356 libtool to reflect this new paradigm. So far, it has proved to be
357 successful: libtool is simpler and more useful than before.
359 The best way to introduce the libtool paradigm is to contrast it with
360 the paradigm of existing library systems, with examples from each. It
361 is a new way of thinking, so it may take a little time to absorb, but
362 when you understand it, the world becomes simpler.
365 File: libtool.info, Node: Using libtool, Next: Invoking libtool, Prev: Libtool paradigm, Up: Top
370 It makes little sense to talk about using libtool in your own packages
371 until you have seen how it makes your life simpler. The examples in
372 this chapter introduce the main features of libtool by comparing the
373 standard library building procedure to libtool's operation on two
377 An Ultrix 4.2 platform with only static libraries.
380 A NetBSD/i386 1.2 platform with shared libraries.
382 You can follow these examples on your own platform, using the
383 preconfigured libtool script that was installed with libtool (*note
386 Source files for the following examples are taken from the `demo'
387 subdirectory of the libtool distribution. Assume that we are building a
388 library, `libhello', out of the files `foo.c' and `hello.c'.
390 Note that the `foo.c' source file uses the `cos' math library
391 function, which is usually found in the standalone math library, and not
392 the C library (*note Trigonometric Functions: (libc)Trig Functions.).
393 So, we need to add `-lm' to the end of the link line whenever we link
394 `foo.lo' into an executable or a library (*note Inter-library
397 The same rule applies whenever you use functions that don't appear in
398 the standard C library... you need to add the appropriate `-lNAME' flag
399 to the end of the link line when you link against those objects.
401 After we have built that library, we want to create a program by
402 linking `main.o' against `libhello'.
406 * Creating object files:: Compiling object files for libraries.
407 * Linking libraries:: Creating libraries from object files.
408 * Linking executables:: Linking object files against libtool libraries.
409 * Debugging executables:: Running GDB on libtool-generated programs.
410 * Installing libraries:: Making libraries available to users.
411 * Installing executables:: Making programs available to users.
412 * Static libraries:: When shared libraries are not wanted.
415 File: libtool.info, Node: Creating object files, Next: Linking libraries, Up: Using libtool
417 3.1 Creating object files
418 =========================
420 To create an object file from a source file, the compiler is invoked
421 with the `-c' flag (and any other desired flags):
423 burger$ gcc -g -O -c main.c
426 The above compiler command produces an object file, usually named
427 `main.o', from the source file `main.c'.
429 For most library systems, creating object files that become part of a
430 static library is as simple as creating object files that are linked to
433 burger$ gcc -g -O -c foo.c
434 burger$ gcc -g -O -c hello.c
437 Shared libraries, however, may only be built from
438 "position-independent code" (PIC). So, special flags must be passed to
439 the compiler to tell it to generate PIC rather than the standard
440 position-dependent code.
442 Since this is a library implementation detail, libtool hides the
443 complexity of PIC compiler flags and uses separate library object files
444 (the PIC one lives in the `.libs' subdirectory and the static one lives
445 in the current directory). On systems without shared libraries, the
446 PIC library object files are not created, whereas on systems where all
447 code is PIC, such as AIX, the static ones are not created.
449 To create library object files for `foo.c' and `hello.c', simply
450 invoke libtool with the standard compilation command as arguments
451 (*note Compile mode::):
453 a23$ libtool --mode=compile gcc -g -O -c foo.c
454 gcc -g -O -c foo.c -o foo.o
455 a23$ libtool --mode=compile gcc -g -O -c hello.c
456 gcc -g -O -c hello.c -o hello.o
459 Note that libtool silently creates an additional control file on each
460 `compile' invocation. The `.lo' file is the libtool object, which
461 Libtool uses to determine what object file may be built into a shared
462 library. On `a23', only static libraries are supported so the library
463 objects look like this:
465 # foo.lo - a libtool object file
466 # Generated by ltmain.sh (GNU libtool) 2.2.10
468 # Please DO NOT delete this file!
469 # It is necessary for linking the library.
471 # Name of the PIC object.
474 # Name of the non-PIC object.
475 non_pic_object='foo.o'
477 On shared library systems, libtool automatically generates an
478 additional PIC object by inserting the appropriate PIC generation flags
479 into the compilation command:
481 burger$ libtool --mode=compile gcc -g -O -c foo.c
483 gcc -g -O -c foo.c -fPIC -DPIC -o .libs/foo.o
484 gcc -g -O -c foo.c -o foo.o >/dev/null 2>&1
487 Note that Libtool automatically created `.libs' directory upon its
488 first execution, where PIC library object files will be stored.
490 Since `burger' supports shared libraries, and requires PIC objects
491 to build them, Libtool has compiled a PIC object this time, and made a
492 note of it in the libtool object:
494 # foo.lo - a libtool object file
495 # Generated by ltmain.sh (GNU libtool) 2.2.10
497 # Please DO NOT delete this file!
498 # It is necessary for linking the library.
500 # Name of the PIC object.
501 pic_object='.libs/foo.o'
503 # Name of the non-PIC object.
504 non_pic_object='foo.o'
506 Notice that the second run of GCC has its output discarded. This is
507 done so that compiler warnings aren't annoyingly duplicated. If you
508 need to see both sets of warnings (you might have conditional code
509 inside `#ifdef PIC' for example), you can turn off suppression with the
510 `-no-suppress' option to libtool's compile mode:
512 burger$ libtool --mode=compile gcc -no-suppress -g -O -c hello.c
513 gcc -g -O -c hello.c -fPIC -DPIC -o .libs/hello.o
514 gcc -g -O -c hello.c -o hello.o
518 File: libtool.info, Node: Linking libraries, Next: Linking executables, Prev: Creating object files, Up: Using libtool
520 3.2 Linking libraries
521 =====================
523 Without libtool, the programmer would invoke the `ar' command to create
526 burger$ ar cru libhello.a hello.o foo.o
529 But of course, that would be too simple, so many systems require that
530 you run the `ranlib' command on the resulting library (to give it
531 better karma, or something):
533 burger$ ranlib libhello.a
536 It seems more natural to use the C compiler for this task, given
537 libtool's "libraries are programs" approach. So, on platforms without
538 shared libraries, libtool simply acts as a wrapper for the system `ar'
539 (and possibly `ranlib') commands.
541 Again, the libtool control file name (`.la' suffix) differs from the
542 standard library name (`.a' suffix). The arguments to libtool are the
543 same ones you would use to produce an executable named `libhello.la'
544 with your compiler (*note Link mode::):
546 a23$ libtool --mode=link gcc -g -O -o libhello.la foo.o hello.o
547 *** Warning: Linking the shared library libhello.la against the non-libtool
548 *** objects foo.o hello.o is not portable!
549 ar cru .libs/libhello.a
550 ranlib .libs/libhello.a
552 (cd .libs && rm -f libhello.la && ln -s ../libhello.la libhello.la)
555 Aha! Libtool caught a common error... trying to build a library
556 from standard objects instead of special `.lo' object files. This
557 doesn't matter so much for static libraries, but on shared library
558 systems, it is of great importance. (Note that you may replace
559 `libhello.la' with `libhello.a' in which case libtool won't issue the
560 warning any more. But although this method works, this is not intended
561 to be used because it makes you lose the benefits of using Libtool.)
563 So, let's try again, this time with the library object files.
564 Remember also that we need to add `-lm' to the link command line because
565 `foo.c' uses the `cos' math library function (*note Using libtool::).
567 Another complication in building shared libraries is that we need to
568 specify the path to the directory in which they (eventually) will be
569 installed (in this case, `/usr/local/lib')(1):
571 a23$ libtool --mode=link gcc -g -O -o libhello.la foo.lo hello.lo \
572 -rpath /usr/local/lib -lm
573 ar cru .libs/libhello.a foo.o hello.o
574 ranlib .libs/libhello.a
576 (cd .libs && rm -f libhello.la && ln -s ../libhello.la libhello.la)
579 Now, let's try the same trick on the shared library platform:
581 burger$ libtool --mode=link gcc -g -O -o libhello.la foo.lo hello.lo \
582 -rpath /usr/local/lib -lm
583 rm -fr .libs/libhello.a .libs/libhello.la
584 ld -Bshareable -o .libs/libhello.so.0.0 .libs/foo.o .libs/hello.o -lm
585 ar cru .libs/libhello.a foo.o hello.o
586 ranlib .libs/libhello.a
588 (cd .libs && rm -f libhello.la && ln -s ../libhello.la libhello.la)
591 Now that's significantly cooler... Libtool just ran an obscure `ld'
592 command to create a shared library, as well as the static library.
594 Note how libtool creates extra files in the `.libs' subdirectory,
595 rather than the current directory. This feature is to make it easier
596 to clean up the build directory, and to help ensure that other programs
597 fail horribly if you accidentally forget to use libtool when you should.
599 Again, you may want to have a look at the `.la' file in order to see
600 what Libtool stores in it. In particular, you will see that Libtool
601 uses this file to remember the destination directory for the library
602 (the argument to `-rpath') as well as the dependency on the math
605 ---------- Footnotes ----------
607 (1) If you don't specify an `rpath', then libtool builds a libtool
608 convenience archive, not a shared library (*note Static libraries::).
611 File: libtool.info, Node: Linking executables, Next: Debugging executables, Prev: Linking libraries, Up: Using libtool
613 3.3 Linking executables
614 =======================
616 If you choose at this point to "install" the library (put it in a
617 permanent location) before linking executables against it, then you
618 don't need to use libtool to do the linking. Simply use the appropriate
619 `-L' and `-l' flags to specify the library's location.
621 Some system linkers insist on encoding the full directory name of
622 each shared library in the resulting executable. Libtool has to work
623 around this misfeature by special magic to ensure that only permanent
624 directory names are put into installed executables.
626 The importance of this bug must not be overlooked: it won't cause
627 programs to crash in obvious ways. It creates a security hole, and
628 possibly even worse, if you are modifying the library source code after
629 you have installed the package, you will change the behaviour of the
632 So, if you want to link programs against the library before you
633 install it, you must use libtool to do the linking.
635 Here's the old way of linking against an uninstalled library:
637 burger$ gcc -g -O -o hell.old main.o libhello.a -lm
640 Libtool's way is almost the same(1) (*note Link mode::):
642 a23$ libtool --mode=link gcc -g -O -o hell main.o libhello.la
643 gcc -g -O -o hell main.o ./.libs/libhello.a -lm
646 That looks too simple to be true. All libtool did was transform
647 `libhello.la' to `./.libs/libhello.a', but remember that `a23' has no
648 shared libraries. Notice that Libtool also remembered that
649 `libhello.la' depends on `-lm', so even though we didn't specify `-lm'
650 on the libtool command line(2) Libtool has added it to the `gcc' link
653 On `burger' Libtool links against the uninstalled shared library:
655 burger$ libtool --mode=link gcc -g -O -o hell main.o libhello.la
656 gcc -g -O -o .libs/hell main.o -L./.libs -R/usr/local/lib -lhello -lm
660 Now assume `libhello.la' had already been installed, and you want to
661 link a new program with it. You could figure out where it lives by
664 burger$ gcc -g -O -o test test.o -L/usr/local/lib -lhello -lm
666 However, unless `/usr/local/lib' is in the standard library search
667 path, you won't be able to run `test'. However, if you use libtool to
668 link the already-installed libtool library, it will do The Right Thing
671 burger$ libtool --mode=link gcc -g -O -o test test.o \
672 /usr/local/lib/libhello.la
673 gcc -g -O -o .libs/test test.o -Wl,--rpath \
674 -Wl,/usr/local/lib /usr/local/lib/libhello.a -lm
678 Note that libtool added the necessary run-time path flag, as well as
679 `-lm', the library libhello.la depended upon. Nice, huh?
681 Notice that the executable, `hell', was actually created in the
682 `.libs' subdirectory. Then, a wrapper script (or, on certain
683 platforms, a wrapper executable *note Wrapper executables::) was
684 created in the current directory.
686 Since libtool created a wrapper script, you should use libtool to
687 install it and debug it too. However, since the program does not depend
688 on any uninstalled libtool library, it is probably usable even without
691 On NetBSD 1.2, libtool encodes the installation directory of
692 `libhello', by using the `-R/usr/local/lib' compiler flag. Then, the
693 wrapper script guarantees that the executable finds the correct shared
694 library (the one in `./.libs') until it is properly installed.
696 Let's compare the two different programs:
698 burger$ time ./hell.old
700 ** This is not GNU Hello. There is no built-in mail reader. **
701 0.21 real 0.02 user 0.08 sys
704 ** This is not GNU Hello. There is no built-in mail reader. **
705 0.63 real 0.09 user 0.59 sys
708 The wrapper script takes significantly longer to execute, but at
709 least the results are correct, even though the shared library hasn't
712 So, what about all the space savings that shared libraries are
715 burger$ ls -l hell.old libhello.a
716 -rwxr-xr-x 1 gord gord 15481 Nov 14 12:11 hell.old
717 -rw-r--r-- 1 gord gord 4274 Nov 13 18:02 libhello.a
718 burger$ ls -l .libs/hell .libs/libhello.*
719 -rwxr-xr-x 1 gord gord 11647 Nov 14 12:10 .libs/hell
720 -rw-r--r-- 1 gord gord 4274 Nov 13 18:44 .libs/libhello.a
721 -rwxr-xr-x 1 gord gord 12205 Nov 13 18:44 .libs/libhello.so.0.0
724 Well, that sucks. Maybe I should just scrap this project and take up
727 Actually, it just proves an important point: shared libraries incur
728 overhead because of their (relative) complexity. In this situation, the
729 price of being dynamic is eight kilobytes, and the payoff is about four
730 kilobytes. So, having a shared `libhello' won't be an advantage until
731 we link it against at least a few more programs.
735 * Wrapper executables:: Wrapper executables for some platforms.
737 ---------- Footnotes ----------
739 (1) However, you should avoid using `-L' or `-l' flags to link
740 against an uninstalled libtool library. Just specify the relative path
741 to the `.la' file, such as `../intl/libintl.la'. This is a design
742 decision to eliminate any ambiguity when linking against uninstalled
745 (2) And why should we? `main.o' doesn't directly depend on `-lm'
749 File: libtool.info, Node: Wrapper executables, Up: Linking executables
751 3.3.1 Wrapper executables for uninstalled programs
752 --------------------------------------------------
754 Some platforms, notably those hosted on Windows such as Cygwin and
755 MinGW, use a wrapper executable rather than a wrapper script to ensure
756 proper operation of uninstalled programs linked by libtool against
757 uninstalled shared libraries. The wrapper executable thus performs the
758 same function as the wrapper script used on other platforms, but allows
759 to satisfy the `make' rules for the program, whose name ends in
760 `$(EXEEXT)'. The actual program executable is created below .libs, and
761 its name will end in `$(EXEEXT)' and may or may not contain an `lt-'
762 prefix. This wrapper executable sets various environment values so
763 that the program executable may locate its (uninstalled) shared
764 libraries, and then launches the program executable.
766 The wrapper executable provides a debug mode, enabled by passing the
767 command-line option `--lt-debug' (see below). When executing in debug
768 mode, diagnostic information will be printed to `stderr' before the
769 program executable is launched.
771 Finally, the wrapper executable supports a number of command line
772 options that may be useful when debugging the operation of the wrapper
773 system. All of these options begin with `--lt-', and if present they
774 and their arguments will be removed from the argument list passed on to
775 the program executable. Therefore, the program executable may not
776 employ command line options that begin with `--lt-'. (In fact, the
777 wrapper executable will detect any command line options that begin with
778 `--lt-' and abort with an error message if the option is not
779 recognized). If this presents a problem, please contact the Libtool
780 team at the Libtool bug reporting address <bug-libtool@gnu.org>.
782 These command line options include:
785 Causes the wrapper to print a copy of the wrapper _script_ to
789 Causes the wrapper to print diagnostic information to `stdout',
790 before launching the program executable.
793 For consistency, both the wrapper _script_ and the wrapper
794 _executable_ support these options.
797 File: libtool.info, Node: Debugging executables, Next: Installing libraries, Prev: Linking executables, Up: Using libtool
799 3.4 Debugging executables
800 =========================
802 If `hell' was a complicated program, you would certainly want to test
803 and debug it before installing it on your system. In the above
804 section, you saw how the libtool wrapper script makes it possible to run
805 the program directly, but unfortunately, this mechanism interferes with
809 GDB is free software and you are welcome to distribute copies of it
810 under certain conditions; type "show copying" to see the conditions.
811 There is no warranty for GDB; type "show warranty" for details.
812 GDB 4.16 (i386-unknown-netbsd), (C) 1996 Free Software Foundation, Inc.
814 "hell": not in executable format: File format not recognized
819 Sad. It doesn't work because GDB doesn't know where the executable
820 lives. So, let's try again, by invoking GDB directly on the executable:
822 burger$ gdb .libs/hell
823 GNU gdb 5.3 (i386-unknown-netbsd)
824 Copyright 2002 Free Software Foundation, Inc.
825 GDB is free software, covered by the GNU General Public License,
826 and you are welcome to change it and/or distribute copies of it
827 under certain conditions. Type "show copying" to see the conditions.
828 There is no warranty for GDB. Type "show warranty" for details.
830 Breakpoint 1 at 0x8048547: file main.c, line 29.
832 Starting program: /home/src/libtool/demo/.libs/hell
833 /home/src/libtool/demo/.libs/hell: can't load library 'libhello.so.0'
835 Program exited with code 020.
839 Argh. Now GDB complains because it cannot find the shared library
840 that `hell' is linked against. So, we must use libtool in order to
841 properly set the library path and run the debugger. Fortunately, we can
842 forget all about the `.libs' directory, and just run it on the
843 executable wrapper (*note Execute mode::):
845 burger$ libtool --mode=execute gdb hell
846 GNU gdb 5.3 (i386-unknown-netbsd)
847 Copyright 2002 Free Software Foundation, Inc.
848 GDB is free software, covered by the GNU General Public License,
849 and you are welcome to change it and/or distribute copies of it
850 under certain conditions. Type "show copying" to see the conditions.
851 There is no warranty for GDB. Type "show warranty" for details.
853 Breakpoint 1 at 0x8048547: file main.c, line 29.
855 Starting program: /home/src/libtool/demo/.libs/hell
857 Breakpoint 1, main (argc=1, argv=0xbffffc40) at main.c:29
858 29 printf ("Welcome to GNU Hell!\n");
860 The program is running. Quit anyway (and kill it)? (y or n) y
864 File: libtool.info, Node: Installing libraries, Next: Installing executables, Prev: Debugging executables, Up: Using libtool
866 3.5 Installing libraries
867 ========================
869 Installing libraries on a non-libtool system is quite
870 straightforward... just copy them into place:(1)
874 burger# cp libhello.a /usr/local/lib/libhello.a
877 Oops, don't forget the `ranlib' command:
879 burger# ranlib /usr/local/lib/libhello.a
882 Libtool installation is quite simple, as well. Just use the
883 `install' or `cp' command that you normally would (*note Install
886 a23# libtool --mode=install cp libhello.la /usr/local/lib/libhello.la
887 cp libhello.la /usr/local/lib/libhello.la
888 cp .libs/libhello.a /usr/local/lib/libhello.a
889 ranlib /usr/local/lib/libhello.a
892 Note that the libtool library `libhello.la' is also installed, to
893 help libtool with uninstallation (*note Uninstall mode::) and linking
894 (*note Linking executables::) and to help programs with dlopening
895 (*note Dlopened modules::).
897 Here is the shared library example:
899 burger# libtool --mode=install install -c libhello.la \
900 /usr/local/lib/libhello.la
901 install -c .libs/libhello.so.0.0 /usr/local/lib/libhello.so.0.0
902 install -c libhello.la /usr/local/lib/libhello.la
903 install -c .libs/libhello.a /usr/local/lib/libhello.a
904 ranlib /usr/local/lib/libhello.a
907 It is safe to specify the `-s' (strip symbols) flag if you use a
908 BSD-compatible install program when installing libraries. Libtool will
909 either ignore the `-s' flag, or will run a program that will strip only
910 debugging and compiler symbols from the library.
912 Once the libraries have been put in place, there may be some
913 additional configuration that you need to do before using them. First,
914 you must make sure that where the library is installed actually agrees
915 with the `-rpath' flag you used to build it.
917 Then, running `libtool -n finish LIBDIR' can give you further hints
918 on what to do (*note Finish mode::):
920 burger# libtool -n finish /usr/local/lib
921 PATH="$PATH:/sbin" ldconfig -m /usr/local/lib
922 -----------------------------------------------------------------
923 Libraries have been installed in:
926 To link against installed libraries in a given directory, LIBDIR,
927 you must use the `-LLIBDIR' flag during linking.
929 You will also need to do one of the following:
930 - add LIBDIR to the `LD_LIBRARY_PATH' environment variable
932 - add LIBDIR to the `LD_RUN_PATH' environment variable
934 - use the `-RLIBDIR' linker flag
936 See any operating system documentation about shared libraries for
937 more information, such as the ld and ld.so manual pages.
938 -----------------------------------------------------------------
941 After you have completed these steps, you can go on to begin using
942 the installed libraries. You may also install any executables that
943 depend on libraries you created.
945 ---------- Footnotes ----------
947 (1) Don't strip static libraries though, or they will be unusable.
950 File: libtool.info, Node: Installing executables, Next: Static libraries, Prev: Installing libraries, Up: Using libtool
952 3.6 Installing executables
953 ==========================
955 If you used libtool to link any executables against uninstalled libtool
956 libraries (*note Linking executables::), you need to use libtool to
957 install the executables after the libraries have been installed (*note
958 Installing libraries::).
960 So, for our Ultrix example, we would run:
962 a23# libtool --mode=install -c hell /usr/local/bin/hell
963 install -c hell /usr/local/bin/hell
966 On shared library systems that require wrapper scripts, libtool just
967 ignores the wrapper script and installs the correct binary:
969 burger# libtool --mode=install -c hell /usr/local/bin/hell
970 install -c .libs/hell /usr/local/bin/hell
974 File: libtool.info, Node: Static libraries, Prev: Installing executables, Up: Using libtool
976 3.7 Linking static libraries
977 ============================
979 Why return to `ar' and `ranlib' silliness when you've had a taste of
980 libtool? Well, sometimes it is desirable to create a static archive
981 that can never be shared. The most frequent case is when you have a
982 set of object files that you use to build several different libraries.
983 You can create a "convenience library" out of those objects, and link
984 against that with the other libraries, instead of listing all the
985 object files every time.
987 If you just want to link this convenience library into programs, then
988 you could just ignore libtool entirely, and use the old `ar' and
989 `ranlib' commands (or the corresponding GNU Automake `_LIBRARIES'
990 rules). You can even install a convenience library using GNU Libtool,
991 though you probably don't want to and hence GNU Automake doesn't allow
994 burger$ libtool --mode=install ./install-sh -c libhello.a \
995 /local/lib/libhello.a
996 ./install-sh -c libhello.a /local/lib/libhello.a
997 ranlib /local/lib/libhello.a
1000 Using libtool for static library installation protects your library
1001 from being accidentally stripped (if the installer used the `-s' flag),
1002 as well as automatically running the correct `ranlib' command.
1004 But libtool libraries are more than just collections of object files:
1005 they can also carry library dependency information, which old archives
1006 do not. If you want to create a libtool static convenience library, you
1007 can omit the `-rpath' flag and use `-static' to indicate that you're
1008 only interested in a static library. When you link a program with such
1009 a library, libtool will actually link all object files and dependency
1010 libraries into the program.
1012 If you omit both `-rpath' and `-static', libtool will create a
1013 convenience library that can be used to create other libtool libraries,
1014 even shared ones. Just like in the static case, the library behaves as
1015 an alias to a set of object files and dependency libraries, but in this
1016 case the object files are suitable for inclusion in shared libraries.
1017 But be careful not to link a single convenience library, directly or
1018 indirectly, into a single program or library, otherwise you may get
1019 errors about symbol redefinitions.
1021 The key is remembering that a convenience library contains PIC
1022 objects, and can be linked where a list of PIC objects makes sense;
1023 i.e. into a shared library. A static convenience library contains
1024 non-PIC objects, so can be linked into an old static library, or a
1027 When GNU Automake is used, you should use `noinst_LTLIBRARIES'
1028 instead of `lib_LTLIBRARIES' for convenience libraries, so that the
1029 `-rpath' option is not passed when they are linked.
1031 As a rule of thumb, link a libtool convenience library into at most
1032 one libtool library, and never into a program, and link libtool static
1033 convenience libraries only into programs, and only if you need to carry
1034 library dependency information to the user of the static convenience
1037 Another common situation where static linking is desirable is in
1038 creating a standalone binary. Use libtool to do the linking and add the
1042 File: libtool.info, Node: Invoking libtool, Next: Integrating libtool, Prev: Using libtool, Up: Top
1044 4 Invoking `libtool'
1045 ********************
1047 The `libtool' program has the following synopsis:
1049 libtool [OPTION]... [MODE-ARG]...
1051 and accepts the following options:
1054 Display libtool configuration variables and exit.
1057 Dump a trace of shell script execution to standard output. This
1058 produces a lot of output, so you may wish to pipe it to `less' (or
1059 `more') or redirect to a file.
1063 Don't create, modify, or delete any files, just show what commands
1064 would be executed by libtool.
1067 Display basic configuration options. This provides a way for
1068 packages to determine whether shared or static libraries will be
1072 Same as `--mode=finish'.
1075 Display short help message.
1078 Display a help message and exit. If `--mode=MODE' is specified,
1079 then detailed help for MODE is displayed.
1082 Display help for the general options as well as detailed help for
1083 each operation mode, and exit.
1086 Use MODE as the operation mode. When using libtool from the
1087 command line, you can give just MODE (or a unique abbreviation of
1088 it) as the first argument as a shorthand for the full
1089 `--mode=MODE'. For example, the following are equivalent:
1091 $ libtool --mode=execute --dry-run gdb prog.exe
1092 $ libtool execute --dry-run gdb prog.exe
1093 $ libtool exe --dry-run gdb prog.exe
1094 $ libtool e --dry-run gdb prog.exe
1096 MODE must be set to one of the following:
1099 Compile a source file into a libtool object.
1102 Automatically set the library path so that another program
1103 can use uninstalled libtool-generated programs or libraries.
1106 Create a library or an executable.
1109 Install libraries or executables.
1112 Complete the installation of libtool libraries on the system.
1115 Delete installed libraries or executables.
1118 Delete uninstalled libraries or executables.
1121 Use configuration variables from tag TAG (*note Tags::).
1123 `--preserve-dup-deps'
1124 Do not remove duplicate dependencies in libraries. When building
1125 packages with static libraries, the libraries may depend
1126 circularly on each other (shared libs can too, but for those it
1127 doesn't matter), so there are situations, where -la -lb -la is
1128 required, and the second -la may not be stripped or the link will
1129 fail. In cases where these duplications are required, this option
1130 will preserve them, only stripping the libraries that libtool
1131 knows it can safely.
1135 Do not print out any progress or informational messages.
1139 Print out progress and informational messages (enabled by default),
1140 as well as additional messages not ordinary seen by default.
1144 Print out the progress and informational messages that are seen by
1145 default. This option has no effect on whether the additional
1146 messages seen in `--verbose' mode are shown.
1149 Do not print out any additional informational messages beyond
1150 those ordinarily seen by default. This option has no effect on
1151 whether the ordinary progress and informational messages enabled
1152 by `--no-quiet' are shown.
1154 Thus, there are now three different message levels (not counting
1155 `--debug'), depending on whether the normal messages and/or the
1156 additional verbose messages are displayed. Note that there is no
1157 mechanism to diplay verbose messages, without also displaying
1161 Normal messages are displayed, verbose messages are not
1162 displayed. In addition to being the default mode, it can be
1163 forcibly achieved by using both option `--no-verbose' and
1164 either option `--no-silent' or option `--no-quiet'.
1167 Neither normal messages nor verbose messages are displayed.
1168 This mode can be achieved using either option `--silent' or
1172 Both normal messages and verbose messages are displayed. This
1173 mode can be achieved using either option `-v' or option
1177 Print libtool version information and exit.
1179 The MODE-ARGS are a variable number of arguments, depending on the
1180 selected operation mode. In general, each MODE-ARG is interpreted by
1181 programs libtool invokes, rather than libtool itself.
1185 * Compile mode:: Creating library object files.
1186 * Link mode:: Generating executables and libraries.
1187 * Execute mode:: Debugging libtool-generated programs.
1188 * Install mode:: Making libraries and executables public.
1189 * Finish mode:: Completing a library installation.
1190 * Uninstall mode:: Removing installed executables and libraries.
1191 * Clean mode:: Removing uninstalled executables and libraries.
1194 File: libtool.info, Node: Compile mode, Next: Link mode, Up: Invoking libtool
1199 For "compile" mode, MODE-ARGS is a compiler command to be used in
1200 creating a "standard" object file. These arguments should begin with
1201 the name of the C compiler, and contain the `-c' compiler flag so that
1202 only an object file is created.
1204 Libtool determines the name of the output file by removing the
1205 directory component from the source file name, then substituting the
1206 source code suffix (e.g. `.c' for C source code) with the library
1207 object suffix, `.lo'.
1209 If shared libraries are being built, any necessary PIC generation
1210 flags are substituted into the compilation command.
1212 The following components of MODE-ARGS are treated specially:
1215 Note that the `-o' option is now fully supported. It is emulated
1216 on the platforms that don't support it (by locking and moving the
1217 objects), so it is really easy to use libtool, just with minor
1218 modifications to your Makefiles. Typing for example
1219 libtool --mode=compile gcc -c foo/x.c -o foo/x.lo
1220 will do what you expect.
1222 Note, however, that, if the compiler does not support `-c' and
1223 `-o', it is impossible to compile `foo/x.c' without overwriting an
1224 existing `./x.o'. Therefore, if you do have a source file
1225 `./x.c', make sure you introduce dependencies in your `Makefile'
1226 to make sure `./x.o' (or `./x.lo') is re-created after any
1227 sub-directory's `x.lo':
1229 x.o x.lo: foo/x.lo bar/x.lo
1231 This will also ensure that make won't try to use a temporarily
1232 corrupted `x.o' to create a program or library. It may cause
1233 needless recompilation on platforms that support `-c' and `-o'
1234 together, but it's the only way to make it safe for those that
1238 If both PIC and non-PIC objects are being built, libtool will
1239 normally suppress the compiler output for the PIC object
1240 compilation to save showing very similar, if not identical
1241 duplicate output for each object. If the `-no-suppress' option is
1242 given in compile mode, libtool will show the compiler output for
1246 Libtool will try to build only PIC objects.
1249 Libtool will try to build only non-PIC objects.
1252 Even if Libtool was configured with `--enable-static', the object
1253 file Libtool builds will not be suitable for static linking.
1254 Libtool will signal an error if it was configured with
1255 `--disable-shared', or if the host does not support shared
1259 Even if libtool was configured with `--disable-static', the object
1260 file Libtool builds *will* be suitable for static linking.
1264 Pass a flag directly to the compiler. With `-Wc,', multiple flags
1265 may be separated by commas, whereas `-Xcompiler ' passes through
1269 File: libtool.info, Node: Link mode, Next: Execute mode, Prev: Compile mode, Up: Invoking libtool
1274 "Link" mode links together object files (including library objects) to
1275 form another library or to create an executable program.
1277 MODE-ARGS consist of a command using the C compiler to create an
1278 output file (with the `-o' flag) from several object files.
1280 The following components of MODE-ARGS are treated specially:
1283 If OUTPUT-FILE is a program, then do not link it against any
1284 shared libraries at all. If OUTPUT-FILE is a library, then only
1285 create a static library. In general, this flag cannot be used
1286 together with `disable-static' (*note LT_INIT::).
1289 Tries to avoid versioning (*note Versioning::) for libraries and
1290 modules, i.e. no version information is stored and no symbolic
1291 links are created. If the platform requires versioning, this
1292 option has no effect.
1295 Pass the absolute name of the directory for installing executable
1296 programs (*note Directory Variables: (standards)Directory
1297 Variables.). `libtool' may use this value to install shared
1298 libraries there on systems that do not provide for any library
1299 hardcoding and use the directory of a program and the `PATH'
1300 variable as library search path. This is typically used for DLLs
1301 on Windows or other systems using the PE (Portable Executable)
1302 format. On other systems, `-bindir' is ignored. The default
1303 value used is `LIBDIR/../bin' for libraries installed to `LIBDIR'.
1304 You should not use `-bindir' for modules.
1307 Same as `-dlpreopen FILE', if native dlopening is not supported on
1308 the host platform (*note Dlopened modules::) or if the program is
1309 linked with `-static', `-static-libtool-libs', or `-all-static'.
1310 Otherwise, no effect. If FILE is `self' Libtool will make sure
1311 that the program can `dlopen' itself, either by enabling
1312 `-export-dynamic' or by falling back to `-dlpreopen self'.
1315 Link FILE into the output program, and add its symbols to the list
1316 of preloaded symbols (*note Dlpreopening::). If FILE is `self',
1317 the symbols of the program itself will be added to preloaded
1318 symbol lists. If FILE is `force' Libtool will make sure that a
1319 preloaded symbol list is always _defined_, regardless of whether
1323 Allow symbols from OUTPUT-FILE to be resolved with `dlsym' (*note
1324 Dlopened modules::).
1326 `-export-symbols SYMFILE'
1327 Tells the linker to export only the symbols listed in SYMFILE.
1328 The symbol file should end in `.sym' and must contain the name of
1329 one symbol per line. This option has no effect on some platforms.
1330 By default all symbols are exported.
1332 `-export-symbols-regex REGEX'
1333 Same as `-export-symbols', except that only symbols matching the
1334 regular expression REGEX are exported. By default all symbols are
1338 Search LIBDIR for required libraries that have already been
1342 OUTPUT-FILE requires the installed library `libNAME'. This option
1343 is required even when OUTPUT-FILE is not an executable.
1346 Creates a library that can be dlopened (*note Dlopened modules::).
1347 This option doesn't work for programs. Module names don't need to
1348 be prefixed with `lib'. In order to prevent name clashes,
1349 however, `libNAME' and `NAME' must not be used at the same time in
1353 Disable fast-install mode for the executable OUTPUT-FILE. Useful
1354 if the program won't be necessarily installed.
1357 Link an executable OUTPUT-FILE that can't be installed and
1358 therefore doesn't need a wrapper script on systems that allow
1359 hardcoding of library paths. Useful if the program is only used
1360 in the build tree, e.g., for testing or generating other files.
1363 Declare that OUTPUT-FILE does not depend on any other libraries.
1364 Some platforms cannot create shared libraries that depend on other
1365 libraries (*note Inter-library dependencies::).
1368 Create OUTPUT-FILE from the specified objects and libraries.
1371 Use a list of object files found in FILE to specify objects.
1373 `-precious-files-regex REGEX'
1374 Prevents removal of files from the temporary output directory whose
1375 names match this regular expression. You might specify `\.bbg?$'
1376 to keep those files created with `gcc -ftest-coverage' for example.
1379 Specify that the library was generated by release RELEASE of your
1380 package, so that users can easily tell which versions are newer
1381 than others. Be warned that no two releases of your package will
1382 be binary compatible if you use this flag. If you want binary
1383 compatibility, use the `-version-info' flag instead (*note
1387 If OUTPUT-FILE is a library, it will eventually be installed in
1388 LIBDIR. If OUTPUT-FILE is a program, add LIBDIR to the run-time
1389 path of the program. On platforms that don't support hardcoding
1390 library paths into executables and only search PATH for shared
1391 libraries, such as when OUTPUT-FILE is a Windows (or other PE
1392 platform) DLL, the `.la' control file will be installed in LIBDIR,
1393 but see `-bindir' above for the eventual destination of the `.dll'
1394 or other library file itself.
1397 If OUTPUT-FILE is a program, add LIBDIR to its run-time path. If
1398 OUTPUT-FILE is a library, add `-RLIBDIR' to its DEPENDENCY_LIBS,
1399 so that, whenever the library is linked into a program, LIBDIR
1400 will be added to its run-time path.
1403 If OUTPUT-FILE is a program, then link it against any uninstalled
1404 shared libtool libraries (this is the default behavior). If
1405 OUTPUT-FILE is a library, then only create a shared library. In
1406 the later case, libtool will signal an error if it was configured
1407 with `--disable-shared', or if the host does not support shared
1411 If OUTPUT-FILE is a libtool library, replace the system's standard
1412 file name extension for shared libraries with SUFFIX (most systems
1413 use `.so' here). This option is helpful in certain cases where an
1414 application requires that shared libraries (typically modules)
1415 have an extension other than the default one. Please note you
1416 must supply the full file name extension including any leading dot.
1419 If OUTPUT-FILE is a program, then do not link it against any
1420 uninstalled shared libtool libraries. If OUTPUT-FILE is a
1421 library, then only create a static library.
1423 `-static-libtool-libs'
1424 If OUTPUT-FILE is a program, then do not link it against any
1425 shared libtool libraries. If OUTPUT-FILE is a library, then only
1426 create a static library.
1428 `-version-info CURRENT[:REVISION[:AGE]]'
1429 If OUTPUT-FILE is a libtool library, use interface version
1430 information CURRENT, REVISION, and AGE to build it (*note
1431 Versioning::). Do *not* use this flag to specify package release
1432 information, rather see the `-release' flag.
1434 `-version-number MAJOR[:MINOR[:REVISION]]'
1435 If OUTPUT-FILE is a libtool library, compute interface version
1436 information so that the resulting library uses the specified
1437 major, minor and revision numbers. This is designed to permit
1438 libtool to be used with existing projects where identical version
1439 numbers are already used across operating systems. New projects
1440 should use the `-version-info' flag instead.
1443 if OUTPUT-FILE is a libtool library, declare that it provides a
1444 weak LIBNAME interface. This is a hint to libtool that there is
1445 no need to append LIBNAME to the list of dependency libraries of
1446 OUTPUT-FILE, because linking against OUTPUT-FILE already supplies
1447 the same interface (*note Linking with dlopened modules::).
1451 Pass a linker-specific flag directly to the compiler. With `-Wc,',
1452 multiple flags may be separated by commas, whereas `-Xcompiler '
1453 passes through commas unchanged.
1457 Pass a linker-specific flag directly to the linker.
1460 Pass a link-specific flag to the compiler driver (CC) during
1463 If the OUTPUT-FILE ends in `.la', then a libtool library is created,
1464 which must be built only from library objects (`.lo' files). The
1465 `-rpath' option is required. In the current implementation, libtool
1466 libraries may not depend on other uninstalled libtool libraries (*note
1467 Inter-library dependencies::).
1469 If the OUTPUT-FILE ends in `.a', then a standard library is created
1470 using `ar' and possibly `ranlib'.
1472 If OUTPUT-FILE ends in `.o' or `.lo', then a reloadable object file
1473 is created from the input files (generally using `ld -r'). This method
1474 is often called "partial linking".
1476 Otherwise, an executable program is created.
1479 File: libtool.info, Node: Execute mode, Next: Install mode, Prev: Link mode, Up: Invoking libtool
1484 For "execute" mode, the library path is automatically set, then a
1485 program is executed.
1487 The first of the MODE-ARGS is treated as a program name, with the
1488 rest as arguments to that program.
1490 The following components of MODE-ARGS are treated specially:
1493 Add the directory containing FILE to the library path.
1495 This mode sets the library path environment variable according to any
1498 If any of the ARGS are libtool executable wrappers, then they are
1499 translated into the name of their corresponding uninstalled binary, and
1500 any of their required library directories are added to the library path.
1503 File: libtool.info, Node: Install mode, Next: Finish mode, Prev: Execute mode, Up: Invoking libtool
1508 In "install" mode, libtool interprets most of the elements of MODE-ARGS
1509 as an installation command beginning with `cp', or a BSD-compatible
1512 The following components of MODE-ARGS are treated specially:
1514 `-inst-prefix-dir INST-PREFIX-DIR'
1515 When installing into a temporary staging area, rather than the
1516 final PREFIX, this argument is used to reflect the temporary path,
1517 in much the same way `automake' uses DESTDIR. For instance, if
1518 PREFIX is `/usr/local', but INST-PREFIX-DIR is `/tmp', then the
1519 object will be installed under `/tmp/usr/local/'. If the
1520 installed object is a libtool library, then the internal fields of
1521 that library will reflect only PREFIX, not INST-PREFIX-DIR:
1523 # Directory that this library needs to be installed in:
1524 libdir='/usr/local/lib'
1528 # Directory that this library needs to be installed in:
1529 libdir='/tmp/usr/local/lib'
1531 `inst-prefix' is also used to insure that if the installed object
1532 must be relinked upon installation, that it is relinked against
1533 the libraries in INST-PREFIX-DIR/PREFIX, not PREFIX.
1535 In truth, this option is not really intended for use when calling
1536 libtool directly; it is automatically used when `libtool
1537 --mode=install' calls `libtool --mode=relink'. Libtool does this
1538 by analyzing the destination path given in the original `libtool
1539 --mode=install' command and comparing it to the expected
1540 installation path established during `libtool --mode=link'.
1542 Thus, end-users need change nothing, and `automake'-style `make
1543 install DESTDIR=/tmp' will Just Work(tm) most of the time. For
1544 systems where fast installation can not be turned on, relinking
1545 may be needed. In this case, a `DESTDIR' install will fail.
1547 Currently it is not generally possible to install into a temporary
1548 staging area that contains needed third-party libraries which are
1549 not yet visible at their final location.
1551 The rest of the MODE-ARGS are interpreted as arguments to the `cp'
1552 or `install' command.
1554 The command is run, and any necessary unprivileged post-installation
1555 commands are also completed.
1558 File: libtool.info, Node: Finish mode, Next: Uninstall mode, Prev: Install mode, Up: Invoking libtool
1563 "Finish" mode helps system administrators install libtool libraries so
1564 that they can be located and linked into user programs.
1566 Each MODE-ARG is interpreted as the name of a library directory.
1567 Running this command may require superuser privileges, so the
1568 `--dry-run' option may be useful.
1571 File: libtool.info, Node: Uninstall mode, Next: Clean mode, Prev: Finish mode, Up: Invoking libtool
1576 "Uninstall" mode deletes installed libraries, executables and objects.
1578 The first MODE-ARG is the name of the program to use to delete files
1579 (typically `/bin/rm').
1581 The remaining MODE-ARGS are either flags for the deletion program
1582 (beginning with a `-'), or the names of files to delete.
1585 File: libtool.info, Node: Clean mode, Prev: Uninstall mode, Up: Invoking libtool
1590 "Clean" mode deletes uninstalled libraries, executables, objects and
1591 libtool's temporary files associated with them.
1593 The first MODE-ARG is the name of the program to use to delete files
1594 (typically `/bin/rm').
1596 The remaining MODE-ARGS are either flags for the deletion program
1597 (beginning with a `-'), or the names of files to delete.
1600 File: libtool.info, Node: Integrating libtool, Next: Other languages, Prev: Invoking libtool, Up: Top
1602 5 Integrating libtool with your package
1603 ***************************************
1605 This chapter describes how to integrate libtool with your packages so
1606 that your users can install hassle-free shared libraries.
1610 * Autoconf macros:: Autoconf macros exported by libtool.
1611 * Makefile rules:: Writing `Makefile' rules for libtool.
1612 * Using Automake:: Automatically supporting libtool.
1613 * Configuring:: Configuring libtool for a host system.
1614 * Distributing:: What files to distribute with your package.
1615 * Static-only libraries:: Sometimes shared libraries are just a pain.
1618 File: libtool.info, Node: Autoconf macros, Next: Makefile rules, Up: Integrating libtool
1620 5.1 Autoconf macros exported by libtool
1621 =======================================
1623 Libtool uses a number of macros to interrogate the host system when it
1624 is being built, and you can use some of them yourself too. Although
1625 there are a great many other macros in the libtool installed m4 files,
1626 these do not form part of the published interface, and are subject to
1627 change between releases.
1629 Macros in the `LT_CMD_' namespace check for various shell commands:
1631 -- Macro: LT_CMD_MAX_LEN
1632 Finds the longest command line that can be safely passed to
1633 `$SHELL' without being truncated, and store in the shell variable
1634 `$max_cmd_len'. It is only an approximate value, but command
1635 lines of this length or shorter are guaranteed not to be truncated.
1637 Macros in the `LT_FUNC_' namespace check characteristics of library
1640 -- Macro: LT_FUNC_DLSYM_USCORE
1641 `AC_DEFINE' the preprocessor symbol `DLSYM_USCORE' if we have to
1642 add an underscore to symbol-names passed in to `dlsym'.
1644 Macros in the `LT_LIB_' namespace check characteristics of system
1648 Set `LIBM' to the math library or libraries required on this
1651 -- Macro: LT_LIB_DLLOAD
1652 This is the macro used by `libltdl' to determine which dlloaders
1653 to use on this machine, if any. Several shell variables are set
1654 (and `AC_SUBST'ed) depending on the dlload interfaces are
1655 available on this machine. `LT_DLLOADERS' contains a list of
1656 libtool libraries that can be used, and if necessary also sets
1657 `LIBADD_DLOPEN' if additional system libraries are required by the
1658 `dlopen' loader, and `LIBADD_SHL_LOAD' if additional system
1659 libraries are required by the `shl_load' loader, respectively.
1660 Finally some symbols are set in `config.h' depending on the
1661 loaders that are found to work: `HAVE_LIBDL', `HAVE_SHL_LOAD',
1662 `HAVE_DYLD', `HAVE_DLD'.
1664 Macros in the `LT_PATH_' namespace search the system for the full path
1665 to particular system commands:
1667 -- Macro: LT_PATH_LD
1668 Add a `--with-gnu-ld' option to `configure'. Try to find the path
1669 to the linker used by `$CC', and whether it is the GNU linker.
1670 The result is stored in the shell variable `$LD', which is
1673 -- Macro: LT_PATH_NM
1674 Try to find a BSD-compatible `nm' or a MS-compatible `dumpbin'
1675 command on this machine. The result is stored in the shell
1676 variable `$NM', which is `AC_SUBST'ed.
1678 Macros in the `LT_SYS_' namespace probe for system characteristics:
1680 -- Macro: LT_SYS_DLOPEN_SELF
1681 Tests whether a program can dlopen itself, and then also whether
1682 the same program can still dlopen itself when statically linked.
1683 Results are stored in the shell variables `$enable_dlopen_self' and
1684 `enable_dlopen_self_static' respectively.
1686 -- Macro: LT_SYS_DLOPEN_DEPLIBS
1687 Define the preprocessor symbol `LTDL_DLOPEN_DEPLIBS' if the OS
1688 needs help to load dependent libraries for `dlopen' (or
1691 -- Macro: LT_SYS_DLSEARCH_PATH
1692 Define the preprocessor symbol `LT_DLSEARCH_PATH' to the system
1693 default library search path.
1695 -- Macro: LT_SYS_MODULE_EXT
1696 Define the preprocessor symbol `LT_MODULE_EXT' to the extension
1697 used for runtime loadable modules. If you use libltdl to open
1698 modules, then you can simply use the libtool library extension,
1701 -- Macro: LT_SYS_MODULE_PATH
1702 Define the preprocessor symbol `LT_MODULE_PATH_VAR' to the name of
1703 the shell environment variable that determines the run-time module
1706 -- Macro: LT_SYS_SYMBOL_USCORE
1707 Set the shell variable `sys_symbol_underscore' to `no' unless the
1708 compiler prefixes global symbols with an underscore.
1711 File: libtool.info, Node: Makefile rules, Next: Using Automake, Prev: Autoconf macros, Up: Integrating libtool
1713 5.2 Writing `Makefile' rules for libtool
1714 ========================================
1716 Libtool is fully integrated with Automake (*note Introduction:
1717 (automake)Top.), starting with Automake version 1.2.
1719 If you want to use libtool in a regular `Makefile' (or
1720 `Makefile.in'), you are on your own. If you're not using Automake, and
1721 you don't know how to incorporate libtool into your package you need to
1722 do one of the following:
1724 1. Download the latest Automake distribution from your nearest GNU
1725 mirror, install it, and start using it.
1727 2. Learn how to write `Makefile' rules by hand. They're sometimes
1728 complex, but if you're clever enough to write rules for compiling
1729 your old libraries, then you should be able to figure out new
1730 rules for libtool libraries (hint: examine the `Makefile.in' in
1731 the `tests/demo' subdirectory of the libtool distribution... note
1732 especially that it was automatically generated from the
1733 `Makefile.am' by Automake).
1736 File: libtool.info, Node: Using Automake, Next: Configuring, Prev: Makefile rules, Up: Integrating libtool
1738 5.3 Using Automake with libtool
1739 ===============================
1741 Libtool library support is implemented under the `LTLIBRARIES' primary.
1743 Here are some samples from the Automake `Makefile.am' in the libtool
1744 distribution's `demo' subdirectory.
1746 First, to link a program against a libtool library, just use the
1747 `program_LDADD'(1) variable:
1749 bin_PROGRAMS = hell hell_static
1751 # Build hell from main.c and libhello.la
1752 hell_SOURCES = main.c
1753 hell_LDADD = libhello.la
1755 # Create a statically linked version of hell.
1756 hell_static_SOURCES = main.c
1757 hell_static_LDADD = libhello.la
1758 hell_static_LDFLAGS = -static
1760 You may use the `program_LDFLAGS' variable to stuff in any flags you
1761 want to pass to libtool while linking `program' (such as `-static' to
1762 avoid linking uninstalled shared libtool libraries).
1764 Building a libtool library is almost as trivial... note the use of
1765 `libhello_la_LDFLAGS' to pass the `-version-info' (*note Versioning::)
1768 # Build a libtool library, libhello.la for installation in libdir.
1769 lib_LTLIBRARIES = libhello.la
1770 libhello_la_SOURCES = hello.c foo.c
1771 libhello_la_LDFLAGS = -version-info 3:12:1
1773 The `-rpath' option is passed automatically by Automake (except for
1774 libraries listed as `noinst_LTLIBRARIES'), so you should not specify it.
1776 *Note Building a Shared Library: (automake)A Shared Library, for
1779 ---------- Footnotes ----------
1781 (1) Since GNU Automake 1.5, the flags `-dlopen' or `-dlpreopen'
1782 (*note Link mode::) can be employed with the PROGRAM_LDADD variable.
1783 Unfortunately, older releases didn't accept these flags, so if you are
1784 stuck with an ancient Automake, we recommend quoting the flag itself,
1785 and setting PROGRAM_DEPENDENCIES too:
1787 program_LDADD = "-dlopen" libfoo.la
1788 program_DEPENDENCIES = libfoo.la
1791 File: libtool.info, Node: Configuring, Next: Distributing, Prev: Using Automake, Up: Integrating libtool
1793 5.4 Configuring libtool
1794 =======================
1796 Libtool requires intimate knowledge of your compiler suite and operating
1797 system in order to be able to create shared libraries and link against
1798 them properly. When you install the libtool distribution, a
1799 system-specific libtool script is installed into your binary directory.
1801 However, when you distribute libtool with your own packages (*note
1802 Distributing::), you do not always know the compiler suite and
1803 operating system that are used to compile your package.
1805 For this reason, libtool must be "configured" before it can be used.
1806 This idea should be familiar to anybody who has used a GNU `configure'
1807 script. `configure' runs a number of tests for system features, then
1808 generates the `Makefile's (and possibly a `config.h' header file),
1809 after which you can run `make' and build the package.
1811 Libtool adds its own tests to your `configure' script in order to
1812 generate a libtool script for the installer's host machine.
1816 * LT_INIT:: Configuring `libtool' in `configure.ac'.
1817 * Configure notes:: Platform-specific notes for configuration.
1820 File: libtool.info, Node: LT_INIT, Next: Configure notes, Up: Configuring
1822 5.4.1 The `LT_INIT' macro
1823 -------------------------
1825 If you are using GNU Autoconf (or Automake), you should add a call to
1826 `LT_INIT' to your `configure.ac' file. This macro adds many new tests
1827 to the `configure' script so that the generated libtool script will
1828 understand the characteristics of the host. It's the most important of
1829 a number of macros defined by Libtool:
1831 -- Macro: LT_PREREQ (VERSION)
1832 Ensure that a recent enough version of Libtool is being used. If
1833 the version of Libtool used for `LT_INIT' is earlier than VERSION,
1834 print an error message to the standard error output and exit with
1835 failure (exit status is 63). For example:
1839 -- Macro: LT_INIT (OPTIONS)
1840 -- Macro: AC_PROG_LIBTOOL
1841 -- Macro: AM_PROG_LIBTOOL
1842 Add support for the `--enable-shared' and `--disable-shared'
1843 `configure' flags.(1) `AC_PROG_LIBTOOL' and `AM_PROG_LIBTOOL' are
1844 deprecated names for older versions of this macro; `autoupdate'
1845 will upgrade your `configure.ac' files.
1847 By default, this macro turns on shared libraries if they are
1848 available, and also enables static libraries if they don't
1849 conflict with the shared libraries. You can modify these defaults
1850 by passing either `disable-shared' or `disable-static' in the
1851 option list to `LT_INIT', or using `AC_DISABLE_SHARED' or
1852 `AC_DISABLE_STATIC'.
1854 # Turn off shared libraries during beta-testing, since they
1855 # make the build process take too long.
1856 LT_INIT([disable-shared])
1858 The user may specify modified forms of the configure flags
1859 `--enable-shared' and `--enable-static' to choose whether shared
1860 or static libraries are built based on the name of the package.
1861 For example, to have shared `bfd' and `gdb' libraries built, but
1862 not shared `libg++', you can run all three `configure' scripts as
1865 trick$ ./configure --enable-shared=bfd,gdb
1867 In general, specifying `--enable-shared=PKGS' is the same as
1868 configuring with `--enable-shared' every package named in the
1869 comma-separated PKGS list, and every other package with
1870 `--disable-shared'. The `--enable-static=PKGS' flag behaves
1871 similarly, but it uses `--enable-static' and `--disable-static'.
1872 The same applies to the `--enable-fast-install=PKGS' flag, which
1873 uses `--enable-fast-install' and `--disable-fast-install'.
1875 The package name `default' matches any packages that have not set
1876 their name in the `PACKAGE' environment variable.
1878 This macro also sets the shell variable LIBTOOL_DEPS, that you can
1879 use to automatically update the libtool script if it becomes
1880 out-of-date. In order to do that, add to your `configure.ac':
1883 AC_SUBST([LIBTOOL_DEPS])
1885 and, to `Makefile.in' or `Makefile.am':
1887 LIBTOOL_DEPS = @LIBTOOL_DEPS@
1888 libtool: $(LIBTOOL_DEPS)
1889 $(SHELL) ./config.status libtool
1891 If you are using GNU Automake, you can omit the assignment, as
1892 Automake will take care of it. You'll obviously have to create
1893 some dependency on `libtool'.
1895 Aside from `disable-static' and `disable-shared', there are other
1896 options that you can pass to `LT_INIT' to modify its behaviour.
1897 Here is a full list:
1900 Enable checking for dlopen support. This option should be
1901 used if the package makes use of the `-dlopen' and
1902 `-dlpreopen' libtool flags, otherwise libtool will assume
1903 that the system does not support dlopening.
1906 This option should be used if the package has been ported to
1907 build clean dlls on win32 platforms. Usually this means that
1908 any library data items are exported with
1909 `__declspec(dllexport)' and imported with
1910 `__declspec(dllimport)'. If this macro is not used, libtool
1911 will assume that the package libraries are not dll clean and
1912 will build only static libraries on win32 hosts.
1914 Provision must be made to pass `-no-undefined' to `libtool'
1915 in link mode from the package `Makefile'. Naturally, if you
1916 pass `-no-undefined', you must ensure that all the library
1917 symbols *really are* defined at link time!
1919 `disable-fast-install'
1920 Change the default behaviour for `LT_INIT' to disable
1921 optimization for fast installation. The user may still
1922 override this default, depending on platform support, by
1923 specifying `--enable-fast-install' to `configure'.
1926 Change the default behaviour for `LT_INIT' to enable shared
1927 libraries. This is the default on all systems where Libtool
1928 knows how to create shared libraries. The user may still
1929 override this default by specifying `--disable-shared' to
1933 Change the default behaviour for `LT_INIT' to disable shared
1934 libraries. The user may still override this default by
1935 specifying `--enable-shared' to `configure'.
1938 Change the default behaviour for `LT_INIT' to enable static
1939 libraries. This is the default on all systems where shared
1940 libraries have been disabled for some reason, and on most
1941 systems where shared libraries have been enabled. If shared
1942 libraries are enabled, the user may still override this
1943 default by specifying `--disable-static' to `configure'.
1946 Change the default behaviour for `LT_INIT' to disable static
1947 libraries. The user may still override this default by
1948 specifying `--enable-static' to `configure'.
1951 Change the default behaviour for `libtool' to try to use only
1952 PIC objects. The user may still override this default by
1953 specifying `--without-pic' to `configure'.
1956 Change the default behaviour of `libtool' to try to use only
1957 non-PIC objects. The user may still override this default by
1958 specifying `--with-pic' to `configure'.
1962 -- Macro: LT_LANG (LANGUAGE)
1963 Enable `libtool' support for the language given if it has not yet
1964 already been enabled. Languages accepted are "C++", "Fortran 77",
1965 "Java" and "Windows Resource".
1967 If Autoconf language support macros such as `AC_PROG_CXX' are used
1968 in your `configure.ac', Libtool language support will automatically
1971 Conversely using `LT_LANG' to enable language support for Libtool
1972 will automatically enable Autoconf language support as well.
1974 Both of the following examples are therefore valid ways of adding
1975 C++ language support to Libtool.
1984 -- Macro: AC_LIBTOOL_DLOPEN
1985 This macro is deprecated, the `dlopen' option to `LT_INIT' should
1988 -- Macro: AC_LIBTOOL_WIN32_DLL
1989 This macro is deprecated, the `win32-dll' option to `LT_INIT'
1990 should be used instead.
1992 -- Macro: AC_DISABLE_FAST_INSTALL
1993 This macro is deprecated, the `disable-fast-install' option to
1994 `LT_INIT' should be used instead.
1996 -- Macro: AC_DISABLE_SHARED
1997 -- Macro: AM_DISABLE_SHARED
1998 Change the default behaviour for `LT_INIT' to disable shared
1999 libraries. The user may still override this default by specifying
2000 `--enable-shared'. The option `disable-shared' to `LT_INIT' is a
2001 shorthand for this. `AM_DISABLE_SHARED' is a deprecated alias for
2002 `AC_DISABLE_SHARED'.
2004 -- Macro: AC_ENABLE_SHARED
2005 -- Macro: AM_ENABLE_SHARED
2006 Change the default behaviour for `LT_INIT' to enable shared
2007 libraries. This is the default on all systems where Libtool knows
2008 how to create shared libraries. The user may still override this
2009 default by specifying `--disable-shared'. The option `shared' to
2010 `LT_INIT' is a shorthand for this. `AM_ENABLE_SHARED' is a
2011 deprecated alias for `AC_ENABLE_SHARED'.
2013 -- Macro: AC_DISABLE_STATIC
2014 -- Macro: AM_DISABLE_STATIC
2015 Change the default behaviour for `LT_INIT' to disable static
2016 libraries. The user may still override this default by specifying
2017 `--enable-static'. The option `disable-static' to `LT_INIT' is a
2018 shorthand for this. `AM_DISABLE_STATIC' is a deprecated alias for
2019 `AC_DISABLE_STATIC'.
2021 -- Macro: AC_ENABLE_STATIC
2022 -- Macro: AM_ENABLE_STATIC
2023 Change the default behaviour for `LT_INIT' to enable static
2024 libraries. This is the default on all systems where shared
2025 libraries have been disabled for some reason, and on most systems
2026 where shared libraries have been enabled. If shared libraries are
2027 enabled, the user may still override this default by specifying
2028 `--disable-static'. The option `static' to `LT_INIT' is a
2029 shorthand for this. `AM_ENABLE_STATIC' is a deprecated alias for
2032 The tests in `LT_INIT' also recognize the following environment
2036 The C compiler that will be used by the generated `libtool'. If
2037 this is not set, `LT_INIT' will look for `gcc' or `cc'.
2040 Compiler flags used to generate standard object files. If this is
2041 not set, `LT_INIT' will not use any such flags. It affects only
2042 the way `LT_INIT' runs tests, not the produced `libtool'.
2044 -- Variable: CPPFLAGS
2045 C preprocessor flags. If this is not set, `LT_INIT' will not use
2046 any such flags. It affects only the way `LT_INIT' runs tests, not
2047 the produced `libtool'.
2050 The system linker to use (if the generated `libtool' requires one).
2051 If this is not set, `LT_INIT' will try to find out what is the
2054 -- Variable: LDFLAGS
2055 The flags to be used by `libtool' when it links a program. If
2056 this is not set, `LT_INIT' will not use any such flags. It
2057 affects only the way `LT_INIT' runs tests, not the produced
2061 The libraries to be used by `LT_INIT' when it links a program. If
2062 this is not set, `LT_INIT' will not use any such flags. It
2063 affects only the way `LT_INIT' runs tests, not the produced
2067 Program to use rather than checking for `nm'.
2070 Program to use rather than checking for `ranlib'.
2073 A command that creates a link of a program, a soft-link if
2074 possible, a hard-link otherwise. `LT_INIT' will check for a
2075 suitable program if this variable is not set.
2077 -- Variable: DLLTOOL
2078 Program to use rather than checking for `dlltool'. Only meaningful
2079 for Cygwin/MS-Windows.
2081 -- Variable: OBJDUMP
2082 Program to use rather than checking for `objdump'. Only meaningful
2083 for Cygwin/MS-Windows.
2086 Program to use rather than checking for `as'. Only used on
2087 Cygwin/MS-Windows at the moment.
2089 With 1.3 era libtool, if you wanted to know any details of what
2090 libtool had discovered about your architecture and environment, you had
2091 to run the script with `--config' and grep through the results. This
2092 idiom was supported up to and including 1.5.x era libtool, where it was
2093 possible to call the generated libtool script from `configure.ac' as
2094 soon as `LT_INIT' had completed. However, one of the features of
2095 libtool 1.4 was that the libtool configuration was migrated out of a
2096 separate `ltconfig' file, and added to the `LT_INIT' macro (nee
2097 `AC_PROG_LIBTOOL'), so the results of the configuration tests were
2098 available directly to code in `configure.ac', rendering the call out to
2099 the generated libtool script obsolete.
2101 Starting with libtool 2.0, the multipass generation of the libtool
2102 script has been consolidated into a single `config.status' pass, which
2103 happens after all the code in `configure.ac' has completed. The
2104 implication of this is that the libtool script does not exist during
2105 execution of code from `configure.ac', and so obviously it cannot be
2106 called for `--config' details anymore. If you are upgrading projects
2107 that used this idiom to libtool 2.0 or newer, you should replace those
2108 calls with direct references to the equivalent Autoconf shell variables
2109 that are set by the configure time tests before being passed to
2110 `config.status' for inclusion in the generated libtool script.
2113 By default, the configured `libtool' script is generated by the
2114 call to `AC_OUTPUT' command, and there is rarely any need to use
2115 `libtool' from `configure'. However, sometimes it is necessary to
2116 run configure time compile and link tests using `libtool'. You
2117 can add `LT_OUTPUT' to your `configure.ac' any time after
2118 `LT_INIT' and any `LT_LANG' calls; that done, `libtool' will be
2119 created by a specially generated `config.lt' file, and available
2120 for use in later tests.
2122 Also, when `LT_OUTPUT' is used, for backwards compatibility with
2123 Automake regeneration rules, `config.status' will call `config.lt'
2124 to regenerate `libtool', rather than generating the file itself.
2126 When you invoke the `libtoolize' program (*note Invoking
2127 libtoolize::), it will tell you where to find a definition of
2128 `LT_INIT'. If you use Automake, the `aclocal' program will
2129 automatically add `LT_INIT' support to your `configure' script when it
2130 sees the invocation of `LT_INIT' in `configure.ac'.
2132 Because of these changes, and the runtime version compatibility
2133 checks Libtool now executes, we now advise *against* including a copy of
2134 `libtool.m4' (and brethren) in `acinclude.m4'. Instead, you should set
2135 your project macro directory with `AC_CONFIG_MACRO_DIR'. When you
2136 `libtoolize' your project, a copy of the relevant macro definitions
2137 will be placed in your `AC_CONFIG_MACRO_DIR', where `aclocal' can
2138 reference them directly from `aclocal.m4'.
2140 ---------- Footnotes ----------
2142 (1) `LT_INIT' requires that you define the `Makefile' variable
2143 `top_builddir' in your `Makefile.in'. Automake does this
2144 automatically, but Autoconf users should set it to the relative path to
2145 the top of your build directory (`../..', for example).
2148 File: libtool.info, Node: Configure notes, Prev: LT_INIT, Up: Configuring
2150 5.4.2 Platform-specific configuration notes
2151 -------------------------------------------
2153 While Libtool tries to hide as many platform-specific features as
2154 possible, some have to be taken into account when configuring either
2155 the Libtool package or a libtoolized package.
2157 * You currently need GNU make to build the Libtool package itself.
2159 * On AIX there are two different styles of shared linking, one in
2160 which symbols are bound at link-time and one in which symbols are
2161 bound at runtime only, similar to ELF. In case of doubt use
2162 `LDFLAGS=-Wl,-brtl' for the latter style.
2164 * On AIX, native tools are to be preferred over binutils; especially
2165 for C++ code, if using the AIX Toolbox GCC 4.0 and binutils,
2166 configure with `AR=/usr/bin/ar LD=/usr/bin/ld NM='/usr/bin/nm -B''.
2168 * On AIX, the `/bin/sh' is very slow due to its inefficient handling
2169 of here-documents. A modern shell is preferable:
2170 CONFIG_SHELL=/bin/bash; export $CONFIG_SHELL
2171 $CONFIG_SHELL ./configure [...]
2173 * For C++ code with templates, it may be necessary to specify the
2174 way the compiler will generate the instantiations. For Portland
2175 pgCC version5, use `CXX='pgCC --one_instantiation_per_object'' and
2176 avoid parallel `make'.
2178 * On Darwin, for C++ code with templates you need two level shared
2179 libraries. Libtool builds these by default if
2180 `MACOSX_DEPLOYMENT_TARGET' is set to 10.3 or later at `configure'
2181 time. See `rdar://problem/4135857' for more information on this
2184 * The default shell on UNICOS 9, a ksh 88e variant, is too buggy to
2185 correctly execute the libtool script. Users are advised to
2186 install a modern shell such as GNU bash.
2188 * Some HP-UX `sed' programs are horribly broken, and cannot handle
2189 libtool's requirements, so users may report unusual problems.
2190 There is no workaround except to install a working `sed' (such as
2191 GNU sed) on these systems.
2193 * The vendor-distributed NCR MP-RAS `cc' programs emits copyright on
2194 standard error that confuse tests on size of `conftest.err'. The
2195 workaround is to specify `CC' when run configure with `CC='cc
2198 * Any earlier DG/UX system with ELF executables, such as R3.10 or
2199 R4.10, is also likely to work, but hasn't been explicitly tested.
2201 * On Reliant Unix libtool has only been tested with the Siemens
2202 C-compiler and an old version of `gcc' provided by Marco Walther.
2204 * `libtool.m4', `ltdl.m4' and the `configure.ac' files are marked to
2205 use autoconf-mode, which is distributed with GNU Emacs 21,
2206 Autoconf itself, and all recent releases of XEmacs.
2208 * When building on some linux systems for multilib targets `libtool'
2209 sometimes guesses the wrong paths that the linker and dynamic
2210 linker search by default. If this occurs, you may override
2211 libtool's guesses at `configure' time by setting the `autoconf'
2212 cache variables `lt_cv_sys_lib_search_path_spec' and
2213 `lt_cv_sys_lib_dlsearch_path_spec' respectively to the correct
2218 File: libtool.info, Node: Distributing, Next: Static-only libraries, Prev: Configuring, Up: Integrating libtool
2220 5.5 Including libtool in your package
2221 =====================================
2223 In order to use libtool, you need to include the following files with
2227 Attempt to guess a canonical system name.
2230 Canonical system name validation subroutine script.
2233 BSD-compatible `install' replacement script.
2236 A generic script implementing basic libtool functionality.
2238 Note that the libtool script itself should _not_ be included with
2239 your package. *Note Configuring::.
2241 You should use the `libtoolize' program, rather than manually
2242 copying these files into your package.
2246 * Invoking libtoolize:: `libtoolize' command line options.
2247 * Autoconf and LTLIBOBJS:: Autoconf automates LTLIBOBJS generation.
2250 File: libtool.info, Node: Invoking libtoolize, Next: Autoconf and LTLIBOBJS, Up: Distributing
2252 5.5.1 Invoking `libtoolize'
2253 ---------------------------
2255 The `libtoolize' program provides a standard way to add libtool support
2256 to your package. In the future, it may implement better usage
2257 checking, or other features to make libtool even easier to use.
2259 The `libtoolize' program has the following synopsis:
2261 libtoolize [OPTION]...
2263 and accepts the following options:
2267 Copy files from the libtool data directory rather than creating
2271 Dump a trace of shell script execution to standard output. This
2272 produces a lot of output, so you may wish to pipe it to `less' (or
2273 `more') or redirect to a file.
2277 Don't run any commands that modify the file system, just print them
2282 Replace existing libtool files. By default, `libtoolize' won't
2283 overwrite existing files.
2286 Display a help message and exit.
2288 `--ltdl [TARGET-DIRECTORY-NAME]'
2289 Install libltdl in the TARGET-DIRECTORY-NAME subdirectory of your
2290 package. Normally, the directory is extracted from the argument
2291 to `LT_CONFIG_LTDL_DIR' in `configure.ac', though you can also
2292 specify a subdirectory name here if you are not using Autoconf for
2293 example. If `libtoolize' can't determine the target directory,
2294 `libltdl' is used as the default.
2297 Normally, Libtoolize tries to diagnose use of deprecated libtool
2298 macros and other stylistic issues. If you are deliberately using
2299 outdated calling conventions, this option prevents Libtoolize from
2300 explaining how to update your project's Libtool conventions.
2303 If passed in conjunction with `--ltdl', this option will cause the
2304 `libltdl' installed by `libtoolize' to be set up for use with a
2305 non-recursive `automake' build. To make use of it, you will need
2306 to add the following to the `Makefile.am' of the parent project:
2308 ## libltdl/Makefile.inc appends to the following variables
2309 ## so we set them here before including it:
2316 noinst_LTLIBRARIES =
2325 include libltdl/Makefile.inc
2330 Work silently. `libtoolize --quiet' is used by GNU Automake to
2331 add libtool files to your package if necessary.
2334 If passed in conjunction with `--ltdl', this option will cause the
2335 `libtoolize' installed `libltdl' to be set up for use with a
2336 recursive `automake' build. To make use of it, you will need to
2337 adjust the parent project's `configure.ac':
2339 AC_CONFIG_FILES([libltdl/Makefile])
2346 If passed in conjunction with `--ltdl', this option will cause the
2347 `libtoolize' installed `libltdl' to be set up for independent
2348 configuration and compilation as a self-contained subproject. To
2349 make use of it, you should arrange for your build to call
2350 `libltdl/configure', and then run `make' in the `libltdl'
2351 directory (or the subdirectory you put libltdl into). If your
2352 project uses Autoconf, you can use the supplied `LT_WITH_LTDL'
2353 macro, or else call `AC_CONFIG_SUBDIRS' directly.
2355 Previous releases of `libltdl' built exclusively in this mode, but
2356 now it is the default mode both for backwards compatibility and
2357 because, for example, it is suitable for use in projects that wish
2358 to use `libltdl', but not use the Autotools for their own build
2363 Work noisily! Give a blow by blow account of what `libtoolize' is
2367 Print `libtoolize' version information and exit.
2369 Sometimes it can be useful to pass options to `libtoolize' even
2370 though it is called by another program, such as `autoreconf'. A
2371 limited number of options are parsed from the environment variable
2372 `LIBTOOLIZE_OPTIONS': currently `--debug', `--no-warn', `--quiet' and
2373 `--verbose'. Multiple options passed in `LIBTOOLIZE_OPTIONS' must be
2374 separated with a space, comma or a colon.
2376 By default, a warning is issued for unknown options found in
2377 `LIBTOOLIZE_OPTIONS' unless the first such option is `--no-warn'.
2378 Where `libtoolize' has always quit on receipt of an unknown option at
2379 the command line, this and all previous releases of `libtoolize' will
2380 continue unabated whatever the content of `LIBTOOLIZE_OPTIONS' (modulo
2381 some possible warning messages).
2383 trick$ LIBTOOLIZE_OPTIONS=--no-warn,--quiet autoreconf --install
2385 If `libtoolize' detects an explicit call to `AC_CONFIG_MACRO_DIR'
2386 (*note The Autoconf Manual: (autoconf)Input.) in your `configure.ac',
2387 it will put the Libtool macros in the specified directory.
2389 In the future other Autotools will automatically check the contents
2390 of `AC_CONFIG_MACRO_DIR', but at the moment it is more portable to add
2391 the macro directory to `ACLOCAL_AMFLAGS' in `Makefile.am', which is
2392 where the tools currently look. If `libtoolize' doesn't see
2393 `AC_CONFIG_MACRO_DIR', it too will honour the first `-I' argument in
2394 `ACLOCAL_AMFLAGS' when choosing a directory to store libtool
2395 configuration macros in. It is perfectly sensible to use both
2396 `AC_CONFIG_MACRO_DIR' and `ACLOCAL_AMFLAGS', as long as they are kept
2399 ACLOCAL_AMFLAGS = -I m4
2401 When you bootstrap your project with `aclocal', then you will need
2402 to explicitly pass the same macro directory with `aclocal''s `-I' flag:
2404 trick$ aclocal -I m4
2406 If `libtoolize' detects an explicit call to `AC_CONFIG_AUX_DIR'
2407 (*note The Autoconf Manual: (autoconf)Input.) in your `configure.ac', it
2408 will put the other support files in the specified directory. Otherwise
2409 they too end up in the project root directory.
2411 Unless `--no-warn' is passed, `libtoolize' displays hints for adding
2412 libtool support to your package, as well.
2415 File: libtool.info, Node: Autoconf and LTLIBOBJS, Prev: Invoking libtoolize, Up: Distributing
2417 5.5.2 Autoconf and `LTLIBOBJS'
2418 ------------------------------
2420 People used to add code like the following to their `configure.ac':
2422 LTLIBOBJS=`echo "$LIBOBJS" | sed 's/\.[^.]* /.lo /g;s/\.[^.]*$/.lo/'`
2423 AC_SUBST([LTLIBOBJS])
2425 This is no longer required (since Autoconf 2.54), and doesn't take
2426 Automake's deansification support into account either, so doesn't work
2427 correctly even with ancient Autoconfs!
2429 Provided you are using a recent (2.54 or better) incarnation of
2430 Autoconf, the call to `AC_OUTPUT' takes care of setting `LTLIBOBJS' up
2431 correctly, so you can simply delete such snippets from your
2432 `configure.ac' if you had them.
2435 File: libtool.info, Node: Static-only libraries, Prev: Distributing, Up: Integrating libtool
2437 5.6 Static-only libraries
2438 =========================
2440 When you are developing a package, it is often worthwhile to configure
2441 your package with the `--disable-shared' flag, or to override the
2442 defaults for `LT_INIT' by using the `disable-shared' option (*note The
2443 `LT_INIT' macro: LT_INIT.). This prevents libtool from building shared
2444 libraries, which has several advantages:
2446 * compilation is twice as fast, which can speed up your development
2449 * debugging is easier because you don't need to deal with any
2450 complexities added by shared libraries, and
2452 * you can see how libtool behaves on static-only platforms.
2454 You may want to put a small note in your package `README' to let
2455 other developers know that `--disable-shared' can save them time. The
2456 following example note is taken from the GIMP(1) distribution `README':
2458 The GIMP uses GNU Libtool in order to build shared libraries on a
2459 variety of systems. While this is very nice for making usable
2460 binaries, it can be a pain when trying to debug a program. For that
2461 reason, compilation of shared libraries can be turned off by
2462 specifying the `--disable-shared' option to `configure'.
2464 ---------- Footnotes ----------
2466 (1) GNU Image Manipulation Program, for those who haven't taken the
2467 plunge. See `http://www.gimp.org/'.
2470 File: libtool.info, Node: Other languages, Next: Versioning, Prev: Integrating libtool, Up: Top
2472 6 Using libtool with other languages
2473 ************************************
2475 Libtool was first implemented in order to add support for writing shared
2476 libraries in the C language. However, over time, libtool is being
2477 integrated with other languages, so that programmers are free to reap
2478 the benefits of shared libraries in their favorite programming language.
2480 This chapter describes how libtool interacts with other languages,
2481 and what special considerations you need to make if you do not use C.
2485 * C++ libraries:: Writing libraries for C++
2489 File: libtool.info, Node: C++ libraries, Next: Tags, Up: Other languages
2491 6.1 Writing libraries for C++
2492 =============================
2494 Creating libraries of C++ code should be a fairly straightforward
2495 process, because its object files differ from C ones in only three ways:
2497 1. Because of name mangling, C++ libraries are only usable by the C++
2498 compiler that created them. This decision was made by the
2499 designers of C++ in order to protect users from conflicting
2500 implementations of features such as constructors, exception
2503 2. On some systems, the C++ compiler must take special actions for the
2504 dynamic linker to run dynamic (i.e., run-time) initializers. This
2505 means that we should not call `ld' directly to link such
2506 libraries, and we should use the C++ compiler instead.
2508 3. C++ compilers will link some Standard C++ library in by default,
2509 but libtool does not know which are these libraries, so it cannot
2510 even run the inter-library dependence analyzer to check how to
2511 link it in. Therefore, running `ld' to link a C++ program or
2512 library is deemed to fail.
2514 Because of these three issues, Libtool has been designed to always
2515 use the C++ compiler to compile and link C++ programs and libraries. In
2516 some instances the `main()' function of a program must also be compiled
2517 with the C++ compiler for static C++ objects to be properly initialized.
2520 File: libtool.info, Node: Tags, Prev: C++ libraries, Up: Other languages
2525 Libtool supports multiple languages through the use of tags.
2526 Technically a tag corresponds to a set of configuration variables
2527 associated with a language. These variables tell `libtool' how it
2528 should create objects and libraries for each language.
2530 Tags are defined at `configure'-time for each language activated in
2531 the package (see `LT_LANG' in *note LT_INIT::). Here is the
2532 correspondence between language names and tags names.
2534 Language name Tag name
2542 `libtool' tries to automatically infer which tag to use from the
2543 compiler command being used to compile or link. If it can't infer a
2544 tag, then it defaults to the configuration for the `C' language.
2546 The tag can also be specified using `libtool''s `--tag=TAG' option
2547 (*note Invoking libtool::). It is a good idea to do so in `Makefile'
2548 rules, because that will allow users to substitute the compiler without
2549 relying on `libtool' inference heuristics. When no tag is specified,
2550 `libtool' will default to `CC'; this tag always exists.
2552 Finally, the set of tags available in a particular project can be
2553 retrieved by tracing for the `LT_SUPPORTED_TAG' macro (*note Trace
2557 File: libtool.info, Node: Versioning, Next: Library tips, Prev: Other languages, Up: Top
2559 7 Library interface versions
2560 ****************************
2562 The most difficult issue introduced by shared libraries is that of
2563 creating and resolving runtime dependencies. Dependencies on programs
2564 and libraries are often described in terms of a single name, such as
2565 `sed'. So, one may say "libtool depends on sed," and that is good
2566 enough for most purposes.
2568 However, when an interface changes regularly, we need to be more
2569 specific: "Gnus 5.1 requires Emacs 19.28 or above." Here, the
2570 description of an interface consists of a name, and a "version number."
2572 Even that sort of description is not accurate enough for some
2573 purposes. What if Emacs 20 changes enough to break Gnus 5.1?
2575 The same problem exists in shared libraries: we require a formal
2576 version system to describe the sorts of dependencies that programs have
2577 on shared libraries, so that the dynamic linker can guarantee that
2578 programs are linked only against libraries that provide the interface
2583 * Interfaces:: What are library interfaces?
2584 * Libtool versioning:: Libtool's versioning system.
2585 * Updating version info:: Changing version information before releases.
2586 * Release numbers:: Breaking binary compatibility for aesthetics.
2589 File: libtool.info, Node: Interfaces, Next: Libtool versioning, Up: Versioning
2591 7.1 What are library interfaces?
2592 ================================
2594 Interfaces for libraries may be any of the following (and more):
2596 * global variables: both names and types
2598 * global functions: argument types and number, return types, and
2601 * standard input, standard output, standard error, and file formats
2603 * sockets, pipes, and other inter-process communication protocol
2606 Note that static functions do not count as interfaces, because they
2607 are not directly available to the user of the library.
2610 File: libtool.info, Node: Libtool versioning, Next: Updating version info, Prev: Interfaces, Up: Versioning
2612 7.2 Libtool's versioning system
2613 ===============================
2615 Libtool has its own formal versioning system. It is not as flexible as
2616 some, but it is definitely the simplest of the more powerful versioning
2619 Think of a library as exporting several sets of interfaces,
2620 arbitrarily represented by integers. When a program is linked against
2621 a library, it may use any subset of those interfaces.
2623 Libtool's description of the interfaces that a program uses is
2624 simple: it encodes the least and the greatest interface numbers in the
2625 resulting binary (FIRST-INTERFACE, LAST-INTERFACE).
2627 The dynamic linker is guaranteed that if a library supports _every_
2628 interface number between FIRST-INTERFACE and LAST-INTERFACE, then the
2629 program can be relinked against that library.
2631 Note that this can cause problems because libtool's compatibility
2632 requirements are actually stricter than is necessary.
2634 Say `libhello' supports interfaces 5, 16, 17, 18, and 19, and that
2635 libtool is used to link `test' against `libhello'.
2637 Libtool encodes the numbers 5 and 19 in `test', and the dynamic
2638 linker will only link `test' against libraries that support _every_
2639 interface between 5 and 19. So, the dynamic linker refuses to link
2640 `test' against `libhello'!
2642 In order to eliminate this problem, libtool only allows libraries to
2643 declare consecutive interface numbers. So, `libhello' can declare at
2644 most that it supports interfaces 16 through 19. Then, the dynamic
2645 linker will link `test' against `libhello'.
2647 So, libtool library versions are described by three integers:
2650 The most recent interface number that this library implements.
2653 The implementation number of the CURRENT interface.
2656 The difference between the newest and oldest interfaces that this
2657 library implements. In other words, the library implements all the
2658 interface numbers in the range from number `CURRENT - AGE' to
2661 If two libraries have identical CURRENT and AGE numbers, then the
2662 dynamic linker chooses the library with the greater REVISION number.
2665 File: libtool.info, Node: Updating version info, Next: Release numbers, Prev: Libtool versioning, Up: Versioning
2667 7.3 Updating library version information
2668 ========================================
2670 If you want to use libtool's versioning system, then you must specify
2671 the version information to libtool using the `-version-info' flag
2672 during link mode (*note Link mode::).
2674 This flag accepts an argument of the form
2675 `CURRENT[:REVISION[:AGE]]'. So, passing `-version-info 3:12:1' sets
2676 CURRENT to 3, REVISION to 12, and AGE to 1.
2678 If either REVISION or AGE are omitted, they default to 0. Also note
2679 that AGE must be less than or equal to the CURRENT interface number.
2681 Here are a set of rules to help you update your library version
2684 1. Start with version information of `0:0:0' for each libtool library.
2686 2. Update the version information only immediately before a public
2687 release of your software. More frequent updates are unnecessary,
2688 and only guarantee that the current interface number gets larger
2691 3. If the library source code has changed at all since the last
2692 update, then increment REVISION (`C:R:A' becomes `C:r+1:A').
2694 4. If any interfaces have been added, removed, or changed since the
2695 last update, increment CURRENT, and set REVISION to 0.
2697 5. If any interfaces have been added since the last public release,
2700 6. If any interfaces have been removed or changed since the last
2701 public release, then set AGE to 0.
2703 *_Never_* try to set the interface numbers so that they correspond
2704 to the release number of your package. This is an abuse that only
2705 fosters misunderstanding of the purpose of library versions. Instead,
2706 use the `-release' flag (*note Release numbers::), but be warned that
2707 every release of your package will not be binary compatible with any
2710 The following explanation may help to understand the above rules a
2711 bit better: consider that there are three possible kinds of reactions
2712 from users of your library to changes in a shared library:
2714 1. Programs using the previous version may use the new version as
2715 drop-in replacement, and programs using the new version can also
2716 work with the previous one. In other words, no recompiling nor
2717 relinking is needed. In this case, bump REVISION only, don't touch
2720 2. Programs using the previous version may use the new version as
2721 drop-in replacement, but programs using the new version may use
2722 APIs not present in the previous one. In other words, a program
2723 linking against the new version may fail with "unresolved symbols"
2724 if linking against the old version at runtime: set REVISION to 0,
2725 bump CURRENT and AGE.
2727 3. Programs may need to be changed, recompiled, relinked in order to
2728 use the new version. Bump CURRENT, set REVISION and AGE to 0.
2730 In the above description, _programs_ using the library in question may
2731 also be replaced by other libraries using it.
2734 File: libtool.info, Node: Release numbers, Prev: Updating version info, Up: Versioning
2736 7.4 Managing release information
2737 ================================
2739 Often, people want to encode the name of the package release into the
2740 shared library so that it is obvious to the user which package their
2741 programs are linked against. This convention is used especially on
2744 trick$ ls /usr/lib/libbfd*
2745 /usr/lib/libbfd.a /usr/lib/libbfd.so.2.7.0.2
2749 On `trick', `/usr/lib/libbfd.so' is a symbolic link to
2750 `libbfd.so.2.7.0.2', which was distributed as a part of
2753 Unfortunately, this convention conflicts directly with libtool's
2754 idea of library interface versions, because the library interface
2755 rarely changes at the same time that the release number does, and the
2756 library suffix is never the same across all platforms.
2758 So, in order to accommodate both views, you can use the `-release'
2759 flag in order to set release information for libraries for which you do
2760 not want to use `-version-info'. For the `libbfd' example, the next
2761 release that uses libtool should be built with `-release 2.9.0', which
2762 will produce the following files on GNU/Linux:
2764 trick$ ls /usr/lib/libbfd*
2765 /usr/lib/libbfd-2.9.0.so /usr/lib/libbfd.a
2769 In this case, `/usr/lib/libbfd.so' is a symbolic link to
2770 `libbfd-2.9.0.so'. This makes it obvious that the user is dealing with
2771 `binutils-2.9.0', without compromising libtool's idea of interface
2774 Note that this option causes a modification of the library name, so
2775 do not use it unless you want to break binary compatibility with any
2776 past library releases. In general, you should only use `-release' for
2777 package-internal libraries or for ones whose interfaces change very
2781 File: libtool.info, Node: Library tips, Next: Inter-library dependencies, Prev: Versioning, Up: Top
2783 8 Tips for interface design
2784 ***************************
2786 Writing a good library interface takes a lot of practice and thorough
2787 understanding of the problem that the library is intended to solve.
2789 If you design a good interface, it won't have to change often, you
2790 won't have to keep updating documentation, and users won't have to keep
2791 relearning how to use the library.
2793 Here is a brief list of tips for library interface design that may
2794 help you in your exploits:
2797 Try to make every interface truly minimal, so that you won't need
2798 to delete entry points very often.
2800 Avoid interface changes
2801 Some people love redesigning and changing entry points just for
2802 the heck of it (note: _renaming_ a function is considered changing
2803 an entry point). Don't be one of those people. If you must
2804 redesign an interface, then try to leave compatibility functions
2805 behind so that users don't need to rewrite their existing code.
2807 Use opaque data types
2808 The fewer data type definitions a library user has access to, the
2809 better. If possible, design your functions to accept a generic
2810 pointer (that you can cast to an internal data type), and provide
2811 access functions rather than allowing the library user to directly
2812 manipulate the data. That way, you have the freedom to change the
2813 data structures without changing the interface.
2815 This is essentially the same thing as using abstract data types and
2816 inheritance in an object-oriented system.
2819 If you are careful to document each of your library's global
2820 functions and variables in header files, and include them in your
2821 library source files, then the compiler will let you know if you
2822 make any interface changes by accident (*note C header files::).
2824 Use the `static' keyword (or equivalent) whenever possible
2825 The fewer global functions your library has, the more flexibility
2826 you'll have in changing them. Static functions and variables may
2827 change forms as often as you like... your users cannot access
2828 them, so they aren't interface changes.
2830 Be careful with array dimensions
2831 The number of elements in a global array is part of an interface,
2832 even if the header just declares `extern int foo[];'. This is
2833 because on i386 and some other SVR4/ELF systems, when an
2834 application references data in a shared library the size of that
2835 data (whatever its type) is included in the application
2836 executable. If you might want to change the size of an array or
2837 string then provide a pointer not the actual array.
2841 * C header files:: How to write portable include files.
2844 File: libtool.info, Node: C header files, Up: Library tips
2846 8.1 Writing C header files
2847 ==========================
2849 Writing portable C header files can be difficult, since they may be read
2850 by different types of compilers:
2853 C++ compilers require that functions be declared with full
2854 prototypes, since C++ is more strongly typed than C. C functions
2855 and variables also need to be declared with the `extern "C"'
2856 directive, so that the names aren't mangled. *Note C++
2857 libraries::, for other issues relevant to using C++ with libtool.
2860 ANSI C compilers are not as strict as C++ compilers, but functions
2861 should be prototyped to avoid unnecessary warnings when the header
2862 file is `#include'd.
2864 non-ANSI C compilers
2865 Non-ANSI compilers will report errors if functions are prototyped.
2867 These complications mean that your library interface headers must use
2868 some C preprocessor magic in order to be usable by each of the above
2871 `foo.h' in the `tests/demo' subdirectory of the libtool distribution
2872 serves as an example for how to write a header file that can be safely
2873 installed in a system directory.
2875 Here are the relevant portions of that file:
2877 /* BEGIN_C_DECLS should be used at the beginning of your declarations,
2878 so that C++ compilers don't mangle their names. Use END_C_DECLS at
2879 the end of C declarations. */
2880 #undef BEGIN_C_DECLS
2883 # define BEGIN_C_DECLS extern "C" {
2884 # define END_C_DECLS }
2886 # define BEGIN_C_DECLS /* empty */
2887 # define END_C_DECLS /* empty */
2890 /* PARAMS is a macro used to wrap function prototypes, so that
2891 compilers that don't understand ANSI C prototypes still work,
2892 and ANSI C compilers can issue warnings about type mismatches. */
2894 #if defined (__STDC__) || defined (_AIX) \
2895 || (defined (__mips) && defined (_SYSTYPE_SVR4)) \
2896 || defined(WIN32) || defined(__cplusplus)
2897 # define PARAMS(protos) protos
2899 # define PARAMS(protos) ()
2902 These macros are used in `foo.h' as follows:
2907 /* The above macro definitions. */
2912 int foo PARAMS((void));
2913 int hello PARAMS((void));
2919 Note that the `#ifndef FOO_H' prevents the body of `foo.h' from
2920 being read more than once in a given compilation.
2922 Also the only thing that must go outside the
2923 `BEGIN_C_DECLS'/`END_C_DECLS' pair are `#include' lines. Strictly
2924 speaking it is only C symbol names that need to be protected, but your
2925 header files will be more maintainable if you have a single pair of
2926 these macros around the majority of the header contents.
2928 You should use these definitions of `PARAMS', `BEGIN_C_DECLS', and
2929 `END_C_DECLS' into your own headers. Then, you may use them to create
2930 header files that are valid for C++, ANSI, and non-ANSI compilers(1).
2932 Do not be naive about writing portable code. Following the tips
2933 given above will help you miss the most obvious problems, but there are
2934 definitely other subtle portability issues. You may need to cope with
2935 some of the following issues:
2937 * Pre-ANSI compilers do not always support the `void *' generic
2938 pointer type, and so need to use `char *' in its place.
2940 * The `const', `inline' and `signed' keywords are not supported by
2941 some compilers, especially pre-ANSI compilers.
2943 * The `long double' type is not supported by many compilers.
2945 ---------- Footnotes ----------
2947 (1) We used to recommend `__P', `__BEGIN_DECLS' and `__END_DECLS'.
2948 This was bad advice since symbols (even preprocessor macro names) that
2949 begin with an underscore are reserved for the use of the compiler.
2952 File: libtool.info, Node: Inter-library dependencies, Next: Dlopened modules, Prev: Library tips, Up: Top
2954 9 Inter-library dependencies
2955 ****************************
2957 By definition, every shared library system provides a way for
2958 executables to depend on libraries, so that symbol resolution is
2959 deferred until runtime.
2961 An "inter-library dependency" is one in which a library depends on
2962 other libraries. For example, if the libtool library `libhello' uses
2963 the `cos' function, then it has an inter-library dependency on `libm',
2964 the math library that implements `cos'.
2966 Some shared library systems provide this feature in an
2967 internally-consistent way: these systems allow chains of dependencies of
2968 potentially infinite length.
2970 However, most shared library systems are restricted in that they only
2971 allow a single level of dependencies. In these systems, programs may
2972 depend on shared libraries, but shared libraries may not depend on other
2975 In any event, libtool provides a simple mechanism for you to declare
2976 inter-library dependencies: for every library `libNAME' that your own
2977 library depends on, simply add a corresponding `-lNAME' option to the
2978 link line when you create your library. To make an example of our
2979 `libhello' that depends on `libm':
2981 burger$ libtool --mode=link gcc -g -O -o libhello.la foo.lo hello.lo \
2982 -rpath /usr/local/lib -lm
2985 When you link a program against `libhello', you don't need to
2986 specify the same `-l' options again: libtool will do that for you, in
2987 order to guarantee that all the required libraries are found. This
2988 restriction is only necessary to preserve compatibility with static
2989 library systems and simple dynamic library systems.
2991 Some platforms, such as AIX, do not even allow you this flexibility.
2992 In order to build a shared library, it must be entirely self-contained
2993 (that is, have references only to symbols that are found in the `.lo'
2994 files or the specified `-l' libraries), and you need to specify the
2995 `-no-undefined' flag. By default, libtool builds only static libraries
2996 on these kinds of platforms.
2998 The simple-minded inter-library dependency tracking code of libtool
2999 releases prior to 1.2 was disabled because it was not clear when it was
3000 possible to link one library with another, and complex failures would
3001 occur. A more complex implementation of this concept was re-introduced
3002 before release 1.3, but it has not been ported to all platforms that
3003 libtool supports. The default, conservative behavior is to avoid
3004 linking one library with another, introducing their inter-dependencies
3005 only when a program is linked with them.
3008 File: libtool.info, Node: Dlopened modules, Next: Using libltdl, Prev: Inter-library dependencies, Up: Top
3013 It can sometimes be confusing to discuss "dynamic linking", because the
3014 term is used to refer to two different concepts:
3016 1. Compiling and linking a program against a shared library, which is
3017 resolved automatically at run time by the dynamic linker. In this
3018 process, dynamic linking is transparent to the application.
3020 2. The application calling functions such as `dlopen' that load
3021 arbitrary, user-specified modules at runtime. This type of dynamic
3022 linking is explicitly controlled by the application.
3024 To mitigate confusion, this manual refers to the second type of
3025 dynamic linking as "dlopening" a module.
3027 The main benefit to dlopening object modules is the ability to access
3028 compiled object code to extend your program, rather than using an
3029 interpreted language. In fact, dlopen calls are frequently used in
3030 language interpreters to provide an efficient way to extend the
3033 As of version 2.2.10, libtool provides support for dlopened modules.
3034 However, you should indicate that your package is willing to use such
3035 support, by using the `LT_INIT' option `dlopen' in `configure.ac'. If
3036 this option is not given, libtool will assume no dlopening mechanism is
3037 available, and will try to simulate it.
3039 This chapter discusses how you as a dlopen application developer
3040 might use libtool to generate dlopen-accessible modules.
3044 * Building modules:: Creating dlopenable objects and libraries.
3045 * Dlpreopening:: Dlopening that works on static platforms.
3046 * Linking with dlopened modules:: Using dlopenable modules in libraries.
3047 * Finding the dlname:: Choosing the right file to `dlopen'.
3048 * Dlopen issues:: Unresolved problems that need your attention.
3051 File: libtool.info, Node: Building modules, Next: Dlpreopening, Up: Dlopened modules
3053 10.1 Building modules to dlopen
3054 ===============================
3056 On some operating systems, a program symbol must be specially declared
3057 in order to be dynamically resolved with the `dlsym' (or equivalent)
3058 function. Libtool provides the `-export-dynamic' and `-module' link
3059 flags (*note Link mode::), for you to make that declaration. You need
3060 to use these flags if you are linking an application program that
3061 dlopens other modules or a libtool library that will also be dlopened.
3063 For example, if we wanted to build a shared library, `hello', that
3064 would later be dlopened by an application, we would add `-module' to
3065 the other link flags:
3067 burger$ libtool --mode=link gcc -module -o hello.la foo.lo \
3068 hello.lo -rpath /usr/local/lib -lm
3071 If symbols from your _executable_ are needed to satisfy unresolved
3072 references in a library you want to dlopen you will have to use the flag
3073 `-export-dynamic'. You should use `-export-dynamic' while linking the
3074 executable that calls dlopen:
3076 burger$ libtool --mode=link gcc -export-dynamic -o helldl main.o
3080 File: libtool.info, Node: Dlpreopening, Next: Linking with dlopened modules, Prev: Building modules, Up: Dlopened modules
3085 Libtool provides special support for dlopening libtool object and
3086 libtool library files, so that their symbols can be resolved _even on
3087 platforms without any `dlopen' and `dlsym' functions_.
3089 Consider the following alternative ways of loading code into your
3090 program, in order of increasing "laziness":
3092 1. Linking against object files that become part of the program
3093 executable, whether or not they are referenced. If an object file
3094 cannot be found, then the compile time linker refuses to create
3097 2. Declaring a static library to the linker, so that it is searched
3098 at link time in order to satisfy any undefined references in the
3099 above object files. If the static library cannot be found, then
3100 the compile time linker refuses to create the executable.
3102 3. Declaring a shared library to the runtime linker, so that it is
3103 searched at runtime in order to satisfy any undefined references
3104 in the above files. If the shared library cannot be found, then
3105 the dynamic linker aborts the program before it runs.
3107 4. Dlopening a module, so that the application can resolve its own,
3108 dynamically-computed references. If there is an error opening the
3109 module, or the module is not found, then the application can
3110 recover without crashing.
3112 Libtool emulates `-dlopen' on static platforms by linking objects
3113 into the program at compile time, and creating data structures that
3114 represent the program's symbol table. In order to use this feature,
3115 you must declare the objects you want your application to dlopen by
3116 using the `-dlopen' or `-dlpreopen' flags when you link your program
3117 (*note Link mode::).
3119 -- Data Type: lt_dlsymlist typedef struct { const char *NAME;
3120 void *ADDRESS; } lt_dlsymlist
3121 The NAME attribute is a null-terminated character string of the
3122 symbol name, such as `"fprintf"'. The ADDRESS attribute is a
3123 generic pointer to the appropriate object, such as `&fprintf'.
3125 -- Variable: const lt_dlsymlist lt_preloaded_symbols[]
3126 An array of LT_DLSYMLIST structures, representing all the preloaded
3127 symbols linked into the program proper. For each module
3128 `-dlpreopen'ed by the Libtool linked program there is an element
3129 with the NAME of the module and an ADDRESS of `0', followed by all
3130 symbols exported from this file. For the executable itself the
3131 special name `@PROGRAM@' is used. The last element of all has a
3132 NAME and ADDRESS of `0'.
3134 To facilitate inclusion of symbol lists into libraries,
3135 `lt_preloaded_symbols' is `#define'd to a suitably unique name in
3138 Some compilers may allow identifiers that are not valid in ANSI C,
3139 such as dollar signs. Libtool only recognizes valid ANSI C symbols (an
3140 initial ASCII letter or underscore, followed by zero or more ASCII
3141 letters, digits, and underscores), so non-ANSI symbols will not appear
3142 in LT_PRELOADED_SYMBOLS.
3144 -- Function: int lt_dlpreload (const lt_dlsymlist *PRELOADED)
3145 Register the list of preloaded modules PRELOADED. If PRELOADED is
3146 `NULL', then all previously registered symbol lists, except the
3147 list set by `lt_dlpreload_default', are deleted. Return 0 on
3150 -- Function: int lt_dlpreload_default (const lt_dlsymlist *PRELOADED)
3151 Set the default list of preloaded modules to PRELOADED, which
3152 won't be deleted by `lt_dlpreload'. Note that this function does
3153 _not_ require libltdl to be initialized using `lt_dlinit' and can
3154 be used in the program to register the default preloaded modules.
3155 Instead of calling this function directly, most programs will use
3156 the macro `LTDL_SET_PRELOADED_SYMBOLS'.
3158 Return 0 on success.
3160 -- Macro: LTDL_SET_PRELOADED_SYMBOLS
3161 Set the default list of preloaded symbols. Should be used in your
3162 program to initialize libltdl's list of preloaded modules.
3168 LTDL_SET_PRELOADED_SYMBOLS();
3172 -- Function Type: int lt_dlpreload_callback_func (lt_dlhandle HANDLE)
3173 Functions of this type can be passed to `lt_dlpreload_open', which
3174 in turn will call back into a function thus passed for each
3175 preloaded module that it opens.
3177 -- Function: int lt_dlpreload_open (const char *ORIGINATOR,
3178 lt_dlpreload_callback_func *FUNC)
3179 Load all of the preloaded modules for ORIGINATOR. For every
3180 module opened in this way, call FUNC.
3182 To open all of the modules preloaded into `libhell.la' (presumably
3183 from within the `libhell.a' initialisation code):
3185 #define preloaded_symbols lt_libhell_LTX_preloaded_symbols
3187 static int hell_preload_callback (lt_dlhandle handle);
3193 if (lt_dlpreload (&preloaded_symbols) == 0)
3195 lt_dlpreload_open ("libhell", preload_callback);
3200 Note that to prevent clashes between multiple preloaded modules,
3201 the preloaded symbols are accessed via a mangled symbol name: to
3202 get the symbols preloaded into `libhell', you must prefix
3203 `preloaded_symbols' with `lt_'; the originator name, `libhell' in
3204 this case; and `_LTX_'. That is,
3205 `lt_libhell_LTX_preloaded_symbols' here.
3208 File: libtool.info, Node: Linking with dlopened modules, Next: Finding the dlname, Prev: Dlpreopening, Up: Dlopened modules
3210 10.3 Linking with dlopened modules
3211 ==================================
3213 When, say, an interpreter application uses dlopened modules to extend
3214 the list of methods it provides, an obvious abstraction for the
3215 maintainers of the interpreter is to have all methods (including the
3216 built in ones supplied with the interpreter) accessed through dlopen.
3217 For one thing, the dlopening functionality will be tested even during
3218 routine invocations. For another, only one subsystem has to be written
3219 for getting methods into the interpreter.
3221 The downside of this abstraction is, of course, that environments
3222 that provide only static linkage can't even load the intrinsic
3223 interpreter methods. Not so! We can statically link those methods by
3224 *dlpreopening* them.
3226 Unfortunately, since platforms such as AIX and cygwin require that
3227 all library symbols must be resolved at compile time, the interpreter
3228 maintainers will need to provide a library to both its own dlpreopened
3229 modules, and third-party modules loaded by dlopen. In itself, that is
3230 not so bad, except that the interpreter too must provide those same
3231 symbols otherwise it will be impossible to resolve all the symbols
3232 required by the modules as they are loaded. Things are even worse if
3233 the code that loads the modules for the interpreter is itself in a
3234 library - and that is usually the case for any non-trivial application.
3235 Modern platforms take care of this by automatically loading all of a
3236 module's dependency libraries as the module is loaded (libltdl can do
3237 this even on platforms that can't do it by themselves). In the end,
3238 this leads to problems with duplicated symbols and prevents modules
3239 from loading, and prevents the application from compiling when modules
3242 ,-------------. ,------------------. ,-----------------.
3243 | Interpreter |----> Module------------> Third-party |
3244 `-------------' | Loader | |Dlopened Modules |
3245 | | | `-----------------'
3246 |,-------v--------.| |
3249 |`----------------'| |
3251 |,-------v--------.| ,--------v--------.
3252 ||Module Interface|| |Module Interface |
3253 || Library || | Library |
3254 |`----------------'| `-----------------'
3255 `------------------'
3257 Libtool has the concept of "weak library interfaces" to circumvent
3258 this problem. Recall that the code that dlopens method-provider
3259 modules for the interpreter application resides in a library: All of
3260 the modules and the dlopener library itself should be linked against
3261 the common library that resolves the module symbols at compile time.
3262 To guard against duplicate symbol definitions, and for dlpreopened
3263 modules to work at all in this scenario, the dlopener library must
3264 declare that it provides a weak library interface to the common symbols
3265 in the library it shares with the modules. That way, when `libtool'
3266 links the *Module Loader* library with some *Dlpreopened Modules* that
3267 were in turn linked against the *Module Interface Library*, it knows
3268 that the *Module Loader* provides an already loaded *Module Interface
3269 Library* to resolve symbols for the *Dlpreopened Modules*, and doesn't
3270 ask the compiler driver to link an identical *Module Interface Library*
3271 dependency library too.
3273 In conjunction with Automake, the `Makefile.am' for the *Module
3274 Loader* might look like this:
3276 lib_LTLIBRARIES = libinterface.la libloader.la
3278 libinterface_la_SOURCES = interface.c interface.h
3279 libinterface_la_LDFLAGS = -version-info 3:2:1
3281 libloader_la_SOURCES = loader.c
3282 libloader_la_LDFLAGS = -weak libinterface.la \
3283 -version-info 3:2:1 \
3284 -dlpreopen ../modules/intrinsics.la
3285 libloader_la_LIBADD = $(libinterface_la_OBJECTS)
3287 And the `Makefile.am' for the `intrinsics.la' module in a sibling
3288 `modules' directory might look like this:
3290 AM_CPPFLAGS = -I$(srcdir)/../libloader
3291 AM_LDFLAGS = -no-undefined -module -avoid-version \
3294 noinst_LTLIBRARIES = intrinsics.la
3296 intrinsics_la_LIBADD = ../libloader/libinterface.la
3298 ../libloader/libinterface.la:
3299 cd ../libloader && $(MAKE) $(AM_MAKEFLAGS) libinterface.la
3301 For a more complex example, see the sources of `libltdl' in the
3302 Libtool distribution, which is built with the help of the `-weak'
3306 File: libtool.info, Node: Finding the dlname, Next: Dlopen issues, Prev: Linking with dlopened modules, Up: Dlopened modules
3308 10.4 Finding the correct name to dlopen
3309 =======================================
3311 After a library has been linked with `-module', it can be dlopened.
3312 Unfortunately, because of the variation in library names, your package
3313 needs to determine the correct file to dlopen.
3315 The most straightforward and flexible implementation is to determine
3316 the name at runtime, by finding the installed `.la' file, and searching
3317 it for the following lines:
3319 # The name that we can `dlopen'.
3322 If DLNAME is empty, then the library cannot be dlopened. Otherwise,
3323 it gives the dlname of the library. So, if the library was installed
3324 as `/usr/local/lib/libhello.la', and the DLNAME was `libhello.so.3',
3325 then `/usr/local/lib/libhello.so.3' should be dlopened.
3327 If your program uses this approach, then it should search the
3328 directories listed in the `LD_LIBRARY_PATH'(1) environment variable, as
3329 well as the directory where libraries will eventually be installed.
3330 Searching this variable (or equivalent) will guarantee that your
3331 program can find its dlopened modules, even before installation,
3332 provided you have linked them using libtool.
3334 ---------- Footnotes ----------
3336 (1) `LIBPATH' on AIX, and `SHLIB_PATH' on HP-UX.
3339 File: libtool.info, Node: Dlopen issues, Prev: Finding the dlname, Up: Dlopened modules
3341 10.5 Unresolved dlopen issues
3342 =============================
3344 The following problems are not solved by using libtool's dlopen support:
3346 * Dlopen functions are generally only available on shared library
3347 platforms. If you want your package to be portable to static
3348 platforms, you have to use either libltdl (*note Using libltdl::)
3349 or develop your own alternatives to dlopening dynamic code. Most
3350 reasonable solutions involve writing wrapper functions for the
3351 `dlopen' family, which do package-specific tricks when dlopening
3352 is unsupported or not available on a given platform.
3354 * There are major differences in implementations of the `dlopen'
3355 family of functions. Some platforms do not even use the same
3356 function names (notably HP-UX, with its `shl_load' family).
3358 * The application developer must write a custom search function in
3359 order to discover the correct module filename to supply to
3363 File: libtool.info, Node: Using libltdl, Next: Trace interface, Prev: Dlopened modules, Up: Top
3368 Libtool provides a small library, called `libltdl', that aims at hiding
3369 the various difficulties of dlopening libraries from programmers. It
3370 consists of a few headers and small C source files that can be
3371 distributed with applications that need dlopening functionality. On
3372 some platforms, whose dynamic linkers are too limited for a simple
3373 implementation of `libltdl' services, it requires GNU DLD, or it will
3374 only emulate dynamic linking with libtool's dlpreopening mechanism.
3376 libltdl supports currently the following dynamic linking mechanisms:
3378 * `dlopen' (Solaris, Linux and various BSD flavors)
3380 * `shl_load' (HP-UX)
3382 * `LoadLibrary' (Win16 and Win32)
3384 * `load_add_on' (BeOS)
3386 * `NSAddImage' or `NSLinkModule' (Darwin and Mac OS X)
3388 * GNU DLD (emulates dynamic linking for static libraries)
3390 * libtool's dlpreopen (see *note Dlpreopening::)
3392 libltdl is licensed under the terms of the GNU Lesser General Public
3393 License, with the following exception:
3395 As a special exception to the GNU Lesser General Public License,
3396 if you distribute this file as part of a program or library that
3397 is built using GNU Libtool, you may include it under the same
3398 distribution terms that you use for the rest of that program.
3402 * Libltdl interface:: How to use libltdl in your programs.
3403 * Modules for libltdl:: Creating modules that can be `dlopen'ed.
3404 * Thread Safety in libltdl:: Registering callbacks for multi-thread safety.
3405 * User defined module data:: Associating data with loaded modules.
3406 * Module loaders for libltdl:: Creating user defined module loaders.
3407 * Distributing libltdl:: How to distribute libltdl with your package.
3410 File: libtool.info, Node: Libltdl interface, Next: Modules for libltdl, Up: Using libltdl
3412 11.1 How to use libltdl in your programs
3413 ========================================
3415 The libltdl API is similar to the dlopen interface of Solaris and Linux,
3416 which is very simple but powerful.
3418 To use libltdl in your program you have to include the header file
3423 The early releases of libltdl used some symbols that violated the POSIX
3424 namespace conventions. These symbols are now deprecated, and have been
3425 replaced by those described here. If you have code that relies on the
3426 old deprecated symbol names, defining `LT_NON_POSIX_NAMESPACE' before
3427 you include `ltdl.h' provides conversion macros. Whichever set of
3428 symbols you use, the new API is not binary compatible with the last, so
3429 you will need to recompile your application in order to use this
3432 Note that libltdl is not well tested in a multithreaded environment,
3433 though the intention is that it should work (*note Using libltdl in a
3434 multi threaded environment: Thread Safety in libltdl.). It was
3435 reported that GNU/Linux's glibc 2.0's `dlopen' with `RTLD_LAZY' (which
3436 libltdl uses by default) is not thread-safe, but this problem is
3437 supposed to be fixed in glibc 2.1. On the other hand, `RTLD_NOW' was
3438 reported to introduce problems in multi-threaded applications on
3439 FreeBSD. Working around these problems is left as an exercise for the
3440 reader; contributions are certainly welcome.
3442 The following macros are defined by including `ltdl.h':
3444 -- Macro: LT_PATHSEP_CHAR
3445 `LT_PATHSEP_CHAR' is the system-dependent path separator, that is,
3446 `;' on Windows and `:' everywhere else.
3448 -- Macro: LT_DIRSEP_CHAR
3449 If `LT_DIRSEP_CHAR' is defined, it can be used as directory
3450 separator in addition to `/'. On Windows, this contains `\'.
3452 The following types are defined in `ltdl.h':
3454 -- Type: lt_dlhandle
3455 `lt_dlhandle' is a module "handle". Every lt_dlopened module has
3456 a handle associated with it.
3458 -- Type: lt_dladvise
3459 `lt_dladvise' is used to control optional module loading modes.
3460 If it is not used, the default mode of the underlying system module
3463 -- Type: lt_dlsymlist
3464 `lt_dlsymlist' is a symbol list for dlpreopened modules. This
3465 structure is described in *note Dlpreopening::.
3467 libltdl provides the following functions:
3469 -- Function: int lt_dlinit (void)
3470 Initialize libltdl. This function must be called before using
3471 libltdl and may be called several times. Return 0 on success,
3472 otherwise the number of errors.
3474 -- Function: int lt_dlexit (void)
3475 Shut down libltdl and close all modules. This function will only
3476 then shut down libltdl when it was called as many times as
3477 `lt_dlinit' has been successfully called. Return 0 on success,
3478 otherwise the number of errors.
3480 -- Function: lt_dlhandle lt_dlopen (const char *FILENAME)
3481 Open the module with the file name FILENAME and return a handle
3482 for it. `lt_dlopen' is able to open libtool dynamic modules,
3483 preloaded static modules, the program itself and native dynamic
3486 Unresolved symbols in the module are resolved using its dependency
3487 libraries and previously dlopened modules. If the executable using
3488 this module was linked with the `-export-dynamic' flag, then the
3489 global symbols in the executable will also be used to resolve
3490 references in the module.
3492 If FILENAME is `NULL' and the program was linked with
3493 `-export-dynamic' or `-dlopen self', `lt_dlopen' will return a
3494 handle for the program itself, which can be used to access its
3497 If libltdl cannot find the library and the file name FILENAME does
3498 not have a directory component it will additionally look in the
3499 following search paths for the module (in the following order):
3501 1. user-defined search path: This search path can be changed by
3502 the program using the functions `lt_dlsetsearchpath',
3503 `lt_dladdsearchdir' and `lt_dlinsertsearchdir'.
3505 2. libltdl's search path: This search path is the value of the
3506 environment variable LTDL_LIBRARY_PATH.
3508 3. system library search path: The system dependent library
3509 search path (e.g. on Linux it is LD_LIBRARY_PATH).
3511 Each search path must be a list of absolute directories separated
3512 by `LT_PATHSEP_CHAR', for example, `"/usr/lib/mypkg:/lib/foo"'.
3513 The directory names may not contain the path separator.
3515 If the same module is loaded several times, the same handle is
3516 returned. If `lt_dlopen' fails for any reason, it returns `NULL'.
3518 -- Function: lt_dlhandle lt_dlopenext (const char *FILENAME)
3519 The same as `lt_dlopen', except that it tries to append different
3520 file name extensions to the file name. If the file with the file
3521 name FILENAME cannot be found libltdl tries to append the
3522 following extensions:
3524 1. the libtool archive extension `.la'
3526 2. the extension used for native dynamically loadable modules on
3527 the host platform, e.g., `.so', `.sl', etc.
3529 This lookup strategy was designed to allow programs that don't
3530 have knowledge about native dynamic libraries naming conventions
3531 to be able to `dlopen' such libraries as well as libtool modules
3534 -- Function: lt_dlhandle lt_dlopenadvise (const char *FILENAME,
3536 The same as `lt_dlopen', except that it also requires an additional
3537 argument which may contain additional hints to the underlying
3538 system module loader. The ADVISE parameter is opaque and can only
3539 be accessed with the functions documented below.
3541 Note that this function does not change the content of ADVISE, so
3542 unlike the other calls in this API takes a direct `lt_dladvise'
3543 type, and not a pointer to the same.
3545 -- Function: int lt_dladvise_init (lt_dladvise *ADVISE)
3546 The ADVISE parameter can be used to pass hints to the module
3547 loader when using `lt_dlopenadvise' to perform the loading. The
3548 ADVISE parameter needs to be initialised by this function before
3549 it can be used. Any memory used by ADVISE needs to be recycled
3550 with `lt_dladvise_destroy' when it is no longer needed.
3552 On failure, `lt_dladvise_init' returns non-zero and sets an error
3553 message that can be retrieved with `lt_dlerror'.
3555 -- Function: int lt_dladvise_destroy (lt_dladvise *ADVISE)
3556 Recycle the memory used by ADVISE. For an example, see the
3557 documentation for `lt_dladvise_ext'.
3559 On failure, `lt_dladvise_destroy' returns non-zero and sets an
3560 error message that can be retrieved with `lt_dlerror'.
3562 -- Function: int lt_dladvise_ext (lt_dladvise *ADVISE)
3563 Set the `ext' hint on ADVISE. Passing an ADVISE parameter to
3564 `lt_dlopenadvise' with this hint set causes it to try to append
3565 different file name extensions like `lt_dlopenext'.
3567 The following example is equivalent to calling `lt_dlopenext
3571 my_dlopenext (const char *filename)
3573 lt_dlhandle handle = 0;
3576 if (!lt_dladvise_init (&advise) && !lt_dladvise_ext (&advise))
3577 handle = lt_dlopenadvise (filename, advise);
3579 lt_dladvise_destroy (&advise);
3584 On failure, `lt_dladvise_ext' returns non-zero and sets an error
3585 message that can be retrieved with `lt_dlerror'.
3587 -- Function: int lt_dladvise_global (lt_dladvise *ADVISE)
3588 Set the `symglobal' hint on ADVISE. Passing an ADVISE parameter
3589 to `lt_dlopenadvise' with this hint set causes it to try to make
3590 the loaded module's symbols globally available for resolving
3591 unresolved symbols in subsequently loaded modules.
3593 If neither the `symglobal' nor the `symlocal' hints are set, or if
3594 a module is loaded without using the `lt_dlopenadvise' call in any
3595 case, then the visibility of the module's symbols will be as per
3596 the default for the underlying module loader and OS. Even if a
3597 suitable hint is passed, not all loaders are able to act upon it in
3598 which case `lt_dlgetinfo' will reveal whether the hint was actually
3601 On failure, `lt_dladvise_global' returns non-zero and sets an error
3602 message that can be retrieved with `lt_dlerror'.
3604 -- Function: int lt_dladvise_local (lt_dladvise *ADVISE)
3605 Set the `symlocal' hint on ADVISE. Passing an ADVISE parameter to
3606 `lt_dlopenadvise' with this hint set causes it to try to keep the
3607 loaded module's symbols hidden so that they are not visible to
3608 subsequently loaded modules.
3610 If neither the `symglobal' nor the `symlocal' hints are set, or if
3611 a module is loaded without using the `lt_dlopenadvise' call in any
3612 case, then the visibility of the module's symbols will be as per
3613 the default for the underlying module loader and OS. Even if a
3614 suitable hint is passed, not all loaders are able to act upon it in
3615 which case `lt_dlgetinfo' will reveal whether the hint was actually
3618 On failure, `lt_dladvise_local' returns non-zero and sets an error
3619 message that can be retrieved with `lt_dlerror'.
3621 -- Function: int lt_dladvise_resident (lt_dladvise *ADVISE)
3622 Set the `resident' hint on ADVISE. Passing an ADVISE parameter to
3623 `lt_dlopenadvise' with this hint set causes it to try to make the
3624 loaded module resident in memory, so that it cannot be unloaded
3625 with a later call to `lt_dlclose'.
3627 On failure, `lt_dladvise_resident' returns non-zero and sets an
3628 error message that can be retrieved with `lt_dlerror'.
3630 -- Function: int lt_dladvise_preload (lt_dladvise *ADVISE)
3631 Set the `preload' hint on ADVISE. Passing an ADVISE parameter to
3632 `lt_dlopenadvise' with this hint set causes it to load only
3633 preloaded modules, so that if a suitable preloaded module is not
3634 found, `lt_dlopenadvise' will return `NULL'.
3636 -- Function: int lt_dlclose (lt_dlhandle HANDLE)
3637 Decrement the reference count on the module HANDLE. If it drops
3638 to zero and no other module depends on this module, then the
3639 module is unloaded. Return 0 on success.
3641 -- Function: void * lt_dlsym (lt_dlhandle HANDLE, const char *NAME)
3642 Return the address in the module HANDLE, where the symbol given by
3643 the null-terminated string NAME is loaded. If the symbol cannot
3644 be found, `NULL' is returned.
3646 -- Function: const char * lt_dlerror (void)
3647 Return a human readable string describing the most recent error
3648 that occurred from any of libltdl's functions. Return `NULL' if
3649 no errors have occurred since initialization or since it was last
3652 -- Function: int lt_dladdsearchdir (const char *SEARCH_DIR)
3653 Append the search directory SEARCH_DIR to the current user-defined
3654 library search path. Return 0 on success.
3656 -- Function: int lt_dlinsertsearchdir (const char *BEFORE,
3657 const char *SEARCH_DIR)
3658 Insert the search directory SEARCH_DIR into the user-defined
3659 library search path, immediately before the element starting at
3660 address BEFORE. If BEFORE is `NULL', then SEARCH_DIR is appending
3661 as if `lt_dladdsearchdir' had been called. Return 0 on success.
3663 -- Function: int lt_dlsetsearchpath (const char *SEARCH_PATH)
3664 Replace the current user-defined library search path with
3665 SEARCH_PATH, which must be a list of absolute directories separated
3666 by `LT_PATHSEP_CHAR'. Return 0 on success.
3668 -- Function: const char * lt_dlgetsearchpath (void)
3669 Return the current user-defined library search path.
3671 -- Function: int lt_dlforeachfile (const char *SEARCH_PATH,
3672 int (*FUNC) (const char *FILENAME, void * DATA), void * DATA)
3673 In some applications you may not want to load individual modules
3674 with known names, but rather find all of the modules in a set of
3675 directories and load them all during initialisation. With this
3676 function you can have libltdl scan the `LT_PATHSEP_CHAR'-delimited
3677 directory list in SEARCH_PATH for candidates, and pass them, along
3678 with DATA to your own callback function, FUNC. If SEARCH_PATH is
3679 `NULL', then search all of the standard locations that `lt_dlopen'
3680 would examine. This function will continue to make calls to FUNC
3681 for each file that it discovers in SEARCH_PATH until one of these
3682 calls returns non-zero, or until the files are exhausted.
3683 `lt_dlforeachfile' returns the value returned by the last call
3686 For example you could define FUNC to build an ordered "argv"-like
3687 vector of files using DATA to hold the address of the start of the
3690 -- Function: int lt_dlmakeresident (lt_dlhandle HANDLE)
3691 Mark a module so that it cannot be `lt_dlclose'd. This can be
3692 useful if a module implements some core functionality in your
3693 project that would cause your code to crash if removed. Return 0
3696 If you use `lt_dlopen (NULL)' to get a HANDLE for the running
3697 binary, that handle will always be marked as resident, and
3698 consequently cannot be successfully `lt_dlclose'd.
3700 -- Function: int lt_dlisresident (lt_dlhandle HANDLE)
3701 Check whether a particular module has been marked as resident,
3702 returning 1 if it has or 0 otherwise. If there is an error while
3703 executing this function, return -1 and set an error message for
3704 retrieval with `lt_dlerror'.
3706 ---------- Footnotes ----------
3708 (1) Some platforms, notably Mac OS X, differentiate between a
3709 runtime library that cannot be opened by `lt_dlopen' and a dynamic
3710 module that can. For maximum portability you should try to ensure that
3711 you only pass `lt_dlopen' objects that have been compiled with libtool's
3715 File: libtool.info, Node: Modules for libltdl, Next: Thread Safety in libltdl, Prev: Libltdl interface, Up: Using libltdl
3717 11.2 Creating modules that can be `dlopen'ed
3718 ============================================
3720 Libtool modules are created like normal libtool libraries with a few
3723 You have to link the module with libtool's `-module' switch, and you
3724 should link any program that is intended to dlopen the module with
3725 `-dlopen MODULENAME.LA' where possible, so that libtool can dlpreopen
3726 the module on platforms that do not support dlopening. If the module
3727 depends on any other libraries, make sure you specify them either when
3728 you link the module or when you link programs that dlopen it. If you
3729 want to disable versioning (*note Versioning::) for a specific module
3730 you should link it with the `-avoid-version' switch. Note that libtool
3731 modules don't need to have a "lib" prefix. However, Automake 1.4 or
3732 higher is required to build such modules.
3734 Usually a set of modules provide the same interface, i.e. exports
3735 the same symbols, so that a program can dlopen them without having to
3736 know more about their internals: In order to avoid symbol conflicts all
3737 exported symbols must be prefixed with "modulename_LTX_" (MODULENAME is
3738 the name of the module). Internal symbols must be named in such a way
3739 that they won't conflict with other modules, for example, by prefixing
3740 them with "_modulename_". Although some platforms support having the
3741 same symbols defined more than once it is generally not portable and it
3742 makes it impossible to dlpreopen such modules.
3744 libltdl will automatically cut the prefix off to get the real name of
3745 the symbol. Additionally, it supports modules that do not use a prefix
3746 so that you can also dlopen non-libtool modules.
3748 `foo1.c' gives an example of a portable libtool module. Exported
3749 symbols are prefixed with "foo1_LTX_", internal symbols with "_foo1_".
3750 Aliases are defined at the beginning so that the code is more readable.
3752 /* aliases for the exported symbols */
3753 #define foo foo1_LTX_foo
3754 #define bar foo1_LTX_bar
3756 /* a global variable definition */
3759 /* a private function */
3760 int _foo1_helper() {
3764 /* an exported function */
3766 return _foo1_helper();
3769 The `Makefile.am' contains the necessary rules to build the module
3773 lib_LTLIBRARIES = foo1.la
3775 foo1_la_SOURCES = foo1.c
3776 foo1_la_LDFLAGS = -module
3780 File: libtool.info, Node: Thread Safety in libltdl, Next: User defined module data, Prev: Modules for libltdl, Up: Using libltdl
3782 11.3 Using libltdl in a multi threaded environment
3783 ==================================================
3785 Libltdl provides a wrapper around whatever dynamic run-time object
3786 loading mechanisms are provided by the host system, many of which are
3787 themselves not thread safe. Consequently libltdl cannot itself be
3788 consistently thread safe.
3790 If you wish to use libltdl in a multithreaded environment, then you
3791 must mutex lock around libltdl calls, since they may in turn be calling
3792 non-thread-safe system calls on some target hosts.
3794 Some old releases of libtool provided a mutex locking API that was
3795 unusable with POSIX threads, so callers were forced to lock around all
3796 libltdl API calls anyway. That mutex locking API was next to useless,
3797 and is not present in current releases.
3799 Some future release of libtool may provide a new POSIX thread
3800 compliant mutex locking API.
3803 File: libtool.info, Node: User defined module data, Next: Module loaders for libltdl, Prev: Thread Safety in libltdl, Up: Using libltdl
3805 11.4 Data associated with loaded modules
3806 ========================================
3808 Some of the internal information about each loaded module that is
3809 maintained by libltdl is available to the user, in the form of this
3812 -- Type: struct lt_dlinfo { char *FILENAME; char *NAME; int REF_COUNT;
3813 int IS_RESIDENT; int IS_SYMGLOBAL; int IS_SYMLOCAL;}
3814 `lt_dlinfo' is used to store information about a module. The
3815 FILENAME attribute is a null-terminated character string of the
3816 real module file name. If the module is a libtool module then
3817 NAME is its module name (e.g. `"libfoo"' for `"dir/libfoo.la"'),
3818 otherwise it is set to `NULL'. The REF_COUNT attribute is a
3819 reference counter that describes how often the same module is
3820 currently loaded. The remaining fields can be compared to any
3821 hints that were passed to `lt_dlopenadvise' to determine whether
3822 the underlying loader was able to follow them.
3824 The following function will return a pointer to libltdl's internal
3825 copy of this structure for the given HANDLE:
3827 -- Function: const lt_dlinfo * lt_dlgetinfo (lt_dlhandle HANDLE)
3828 Return a pointer to a struct that contains some information about
3829 the module HANDLE. The contents of the struct must not be
3830 modified. Return `NULL' on failure.
3832 Furthermore, in order to save you from having to keep a list of the
3833 handles of all the modules you have loaded, these functions allow you to
3834 iterate over libltdl's list of loaded modules:
3836 -- Type: lt_dlinterface_id
3837 The opaque type used to hold the module interface details for each
3838 registered libltdl client.
3840 -- Type: int lt_dlhandle_interface (lt_dlhandle HANDLE,
3841 const char *ID_STRING)
3842 Functions of this type are called to check that a handle conforms
3843 to a library's expected module interface when iterating over the
3844 global handle list. You should be careful to write a callback
3845 function of this type that can correctly identify modules that
3846 belong to this client, both to prevent other clients from
3847 accidentally finding your loaded modules with the iterator
3848 functions below, and vice versa. The best way to do this is to
3849 check that module HANDLE conforms to the interface specification
3850 of your loader using `lt_dlsym'.
3852 The callback may be given *every* module loaded by all the libltdl
3853 module clients in the current address space, including any modules
3854 loaded by other libraries such as libltdl itself, and should
3855 return non-zero if that module does not fulfill the interface
3856 requirements of your loader.
3859 my_interface_cb (lt_dlhandle handle, const char *id_string)
3861 char *(*module_id) (void) = NULL;
3863 /* A valid my_module must provide all of these symbols. */
3864 if (!((module_id = (char*(*)(void)) lt_dlsym ("module_version"))
3865 && lt_dlsym ("my_module_entrypoint")))
3868 if (strcmp (id_string, module_id()) != 0)
3874 -- Function: lt_dlinterface_id lt_dlinterface_register
3875 (const char *ID_STRING, lt_dlhandle_interface *IFACE)
3876 Use this function to register your interface validator with
3877 libltdl, and in return obtain a unique key to store and retrieve
3878 per-module data. You supply an ID_STRING and IFACE so that the
3879 resulting `lt_dlinterface_id' can be used to filter the module
3880 handles returned by the iteration functions below. If IFACE is
3881 `NULL', all modules will be matched.
3883 -- Function: void lt_dlinterface_free (lt_dlinterface_id IFACE)
3884 Release the data associated with IFACE.
3886 -- Function: int lt_dlhandle_map (lt_dlinterface_id IFACE,
3887 int (*FUNC) (lt_dlhandle HANDLE, void * DATA), void * DATA)
3888 For each module that matches IFACE, call the function FUNC. When
3889 writing the FUNC callback function, the argument HANDLE is the
3890 handle of a loaded module, and DATA is the last argument passed to
3891 `lt_dlhandle_map'. As soon as FUNC returns a non-zero value for
3892 one of the handles, `lt_dlhandle_map' will stop calling FUNC and
3893 immediately return that non-zero value. Otherwise 0 is eventually
3894 returned when FUNC has been successfully called for all matching
3897 -- Function: lt_dlhandle lt_dlhandle_iterate (lt_dlinterface_id IFACE,
3899 Iterate over the module handles loaded by IFACE, returning the
3900 first matching handle in the list if PLACE is `NULL', and the next
3901 one on subsequent calls. If PLACE is the last element in the list
3902 of eligible modules, this function returns `NULL'.
3904 lt_dlhandle handle = 0;
3905 lt_dlinterface_id iface = my_interface_id;
3907 while ((handle = lt_dlhandle_iterate (iface, handle)))
3912 -- Function: lt_dlhandle lt_dlhandle_fetch (lt_dlinterface_id IFACE,
3913 const char *MODULE_NAME)
3914 Search through the module handles loaded by IFACE for a module
3915 named MODULE_NAME, returning its handle if found or else `NULL' if
3916 no such named module has been loaded by IFACE.
3918 However, you might still need to maintain your own list of loaded
3919 module handles (in parallel with the list maintained inside libltdl) if
3920 there were any other data that your application wanted to associate
3921 with each open module. Instead, you can use the following API calls to
3922 do that for you. You must first obtain a unique interface id from
3923 libltdl as described above, and subsequently always use it to retrieve
3924 the data you stored earlier. This allows different libraries to each
3925 store their own data against loaded modules, without interfering with
3928 -- Function: void * lt_dlcaller_set_data (lt_dlinterface_id KEY,
3929 lt_dlhandle HANDLE, void * DATA)
3930 Set DATA as the set of data uniquely associated with KEY and
3931 HANDLE for later retrieval. This function returns the DATA
3932 previously associated with KEY and HANDLE if any. A result of 0,
3933 may indicate that a diagnostic for the last error (if any) is
3934 available from `lt_dlerror()'.
3936 For example, to correctly remove some associated data:
3938 void *stale = lt_dlcaller_set_data (key, handle, 0);
3945 char *error_msg = lt_dlerror ();
3947 if (error_msg != NULL)
3949 my_error_handler (error_msg);
3950 return STATUS_FAILED;
3954 -- Function: void * lt_dlcaller_get_data (lt_dlinterface_id KEY,
3956 Return the address of the data associated with KEY and HANDLE, or
3957 else `NULL' if there is none.
3959 Old versions of libltdl also provided a simpler, but similar, API
3960 based around `lt_dlcaller_id'. Unfortunately, it had no provision for
3961 detecting whether a module belonged to a particular interface as
3962 libltdl didn't support multiple loaders in the same address space at
3963 that time. Those APIs are no longer supported as there would be no way
3964 to stop clients of the old APIs from seeing (and accidentally altering)
3965 modules loaded by other libraries.
3968 File: libtool.info, Node: Module loaders for libltdl, Next: Distributing libltdl, Prev: User defined module data, Up: Using libltdl
3970 11.5 How to create and register new module loaders
3971 ==================================================
3973 Sometimes libltdl's many ways of gaining access to modules are not
3974 sufficient for the purposes of a project. You can write your own
3975 loader, and register it with libltdl so that `lt_dlopen' will be able
3978 Writing a loader involves writing at least three functions that can
3979 be called by `lt_dlopen', `lt_dlsym' and `lt_dlclose'. Optionally, you
3980 can provide a finalisation function to perform any cleanup operations
3981 when `lt_dlexit' executes, and a symbol prefix string that will be
3982 prepended to any symbols passed to `lt_dlsym'. These functions must
3983 match the function pointer types below, after which they can be
3984 allocated to an instance of `lt_user_dlloader' and registered.
3986 Registering the loader requires that you choose a name for it, so
3987 that it can be recognised by `lt_dlloader_find' and removed with
3988 `lt_dlloader_remove'. The name you choose must be unique, and not
3989 already in use by libltdl's builtin loaders:
3992 The system dynamic library loader, if one exists.
3995 The GNU dld loader, if `libdld' was installed when libltdl was
3999 The loader for `lt_dlopen'ing of preloaded static modules.
4001 The prefix "dl" is reserved for loaders supplied with future
4002 versions of libltdl, so you should not use that for your own loader
4005 The following types are defined in `ltdl.h':
4008 `lt_module' is a dlloader dependent module. The dynamic module
4009 loader extensions communicate using these low level types.
4011 -- Type: lt_dlloader
4012 `lt_dlloader' is a handle for module loader types.
4014 -- Type: lt_user_data
4015 `lt_user_data' is used for specifying loader instance data.
4017 -- Type: struct lt_user_dlloader {const char *SYM_PREFIX;
4018 lt_module_open *MODULE_OPEN; lt_module_close *MODULE_CLOSE;
4019 lt_find_sym *FIND_SYM; lt_dlloader_exit *DLLOADER_EXIT; }
4020 If you want to define a new way to open dynamic modules, and have
4021 the `lt_dlopen' API use it, you need to instantiate one of these
4022 structures and pass it to `lt_dlloader_add'. You can pass whatever
4023 you like in the DLLOADER_DATA field, and it will be passed back as
4024 the value of the first parameter to each of the functions
4025 specified in the function pointer fields.
4027 -- Type: lt_module lt_module_open (const char *FILENAME)
4028 The type of the loader function for an `lt_dlloader' module
4029 loader. The value set in the dlloader_data field of the `struct
4030 lt_user_dlloader' structure will be passed into this function in
4031 the LOADER_DATA parameter. Implementation of such a function
4032 should attempt to load the named module, and return an `lt_module'
4033 suitable for passing in to the associated `lt_module_close' and
4034 `lt_sym_find' function pointers. If the function fails it should
4035 return `NULL', and set the error message with `lt_dlseterror'.
4037 -- Type: int lt_module_close (lt_user_data LOADER_DATA,
4039 The type of the unloader function for a user defined module loader.
4040 Implementation of such a function should attempt to release any
4041 resources tied up by the MODULE module, and then unload it from
4042 memory. If the function fails for some reason, set the error
4043 message with `lt_dlseterror' and return non-zero.
4045 -- Type: void * lt_find_sym (lt_module MODULE, const char *SYMBOL)
4046 The type of the symbol lookup function for a user defined module
4047 loader. Implementation of such a function should return the
4048 address of the named SYMBOL in the module MODULE, or else set the
4049 error message with `lt_dlseterror' and return `NULL' if lookup
4052 -- Type: int lt_dlloader_exit (lt_user_data LOADER_DATA)
4053 The type of the finalisation function for a user defined module
4054 loader. Implementation of such a function should free any
4055 resources associated with the loader, including any user specified
4056 data in the `dlloader_data' field of the `lt_user_dlloader'. If
4057 non-`NULL', the function will be called by `lt_dlexit', and
4058 `lt_dlloader_remove'.
4063 register_myloader (void)
4065 lt_user_dlloader dlloader;
4067 /* User modules are responsible for their own initialisation. */
4068 if (myloader_init () != 0)
4069 return MYLOADER_INIT_ERROR;
4071 dlloader.sym_prefix = NULL;
4072 dlloader.module_open = myloader_open;
4073 dlloader.module_close = myloader_close;
4074 dlloader.find_sym = myloader_find_sym;
4075 dlloader.dlloader_exit = myloader_exit;
4076 dlloader.dlloader_data = (lt_user_data)myloader_function;
4078 /* Add my loader as the default module loader. */
4079 if (lt_dlloader_add (lt_dlloader_next (NULL), &dlloader, "myloader") != 0)
4085 Note that if there is any initialisation required for the loader, it
4086 must be performed manually before the loader is registered - libltdl
4087 doesn't handle user loader initialisation.
4089 Finalisation _is_ handled by libltdl however, and it is important to
4090 ensure the `dlloader_exit' callback releases any resources claimed
4091 during the initialisation phase.
4093 libltdl provides the following functions for writing your own module
4096 -- Function: int lt_dlloader_add (lt_dlloader *PLACE,
4097 lt_user_dlloader *DLLOADER, const char *LOADER_NAME)
4098 Add a new module loader to the list of all loaders, either as the
4099 last loader (if PLACE is `NULL'), else immediately before the
4100 loader passed as PLACE. LOADER_NAME will be returned by
4101 `lt_dlloader_name' if it is subsequently passed a newly registered
4102 loader. These LOADER_NAMEs must be unique, or
4103 `lt_dlloader_remove' and `lt_dlloader_find' cannot work. Returns
4106 /* Make myloader be the last one. */
4107 if (lt_dlloader_add (NULL, myloader) != 0)
4108 perror (lt_dlerror ());
4110 -- Function: int lt_dlloader_remove (const char *LOADER_NAME)
4111 Remove the loader identified by the unique name, LOADER_NAME.
4112 Before this can succeed, all modules opened by the named loader
4113 must have been closed. Returns 0 for success, otherwise an error
4114 message can be obtained from `lt_dlerror'.
4116 /* Remove myloader. */
4117 if (lt_dlloader_remove ("myloader") != 0)
4118 perror (lt_dlerror ());
4120 -- Function: lt_dlloader * lt_dlloader_next (lt_dlloader *PLACE)
4121 Iterate over the module loaders, returning the first loader if
4122 PLACE is `NULL', and the next one on subsequent calls. The handle
4123 is for use with `lt_dlloader_add'.
4125 /* Make myloader be the first one. */
4126 if (lt_dlloader_add (lt_dlloader_next (NULL), myloader) != 0)
4129 -- Function: lt_dlloader * lt_dlloader_find (const char *LOADER_NAME)
4130 Return the first loader with a matching LOADER_NAME identifier, or
4131 else `NULL', if the identifier is not found.
4133 The identifiers that may be used by libltdl itself, if the host
4134 architecture supports them are "dlopen"(1), "dld" and "dlpreload".
4136 /* Add a user loader as the next module loader to be tried if
4137 the standard dlopen loader were to fail when lt_dlopening. */
4138 if (lt_dlloader_add (lt_dlloader_find ("dlopen"), myloader) != 0)
4141 -- Function: const char * lt_dlloader_name (lt_dlloader *PLACE)
4142 Return the identifying name of PLACE, as obtained from
4143 `lt_dlloader_next' or `lt_dlloader_find'. If this function fails,
4144 it will return `NULL' and set an error for retrieval with
4147 -- Function: lt_user_data * lt_dlloader_data (lt_dlloader *PLACE)
4148 Return the address of the `dlloader_data' of PLACE, as obtained
4149 from `lt_dlloader_next' or `lt_dlloader_find'. If this function
4150 fails, it will return `NULL' and set an error for retrieval with
4153 11.5.1 Error handling within user module loaders
4154 ------------------------------------------------
4156 -- Function: int lt_dladderror (const char *DIAGNOSTIC)
4157 This function allows you to integrate your own error messages into
4158 `lt_dlerror'. Pass in a suitable diagnostic message for return by
4159 `lt_dlerror', and an error identifier for use with `lt_dlseterror'
4162 If the allocation of an identifier fails, this function returns -1.
4164 int myerror = lt_dladderror ("Doh!");
4166 perror (lt_dlerror ());
4168 -- Function: int lt_dlseterror (int ERRORCODE)
4169 When writing your own module loaders, you should use this function
4170 to raise errors so that they are propagated through the
4171 `lt_dlerror' interface. All of the standard errors used by
4172 libltdl are declared in `ltdl.h', or you can add more of your own
4173 with `lt_dladderror'. This function returns 0 on success.
4175 if (lt_dlseterror (LTDL_ERROR_NO_MEMORY) != 0)
4176 perror (lt_dlerror ());
4178 ---------- Footnotes ----------
4180 (1) This is used for the host dependent module loading API -
4181 `shl_load' and `LoadLibrary' for example
4184 File: libtool.info, Node: Distributing libltdl, Prev: Module loaders for libltdl, Up: Using libltdl
4186 11.6 How to distribute libltdl with your package
4187 ================================================
4189 Even though libltdl is installed together with libtool, you may wish to
4190 include libltdl in the distribution of your package, for the
4191 convenience of users of your package that don't have libtool or libltdl
4192 installed, or if you are using features of a very new version of
4193 libltdl that you don't expect your users to have yet. In such cases,
4194 you must decide which flavor of libltdl you want to use: a convenience
4195 library or an installable libtool library.
4197 The most simplistic way to add `libltdl' to your package is to copy
4198 all the `libltdl' source files to a subdirectory within your package
4199 and to build and link them along with the rest of your sources. To
4200 help you do this, the m4 macros for Autoconf are available in
4201 `ltdl.m4'. You must ensure that they are available in `aclocal.m4'
4202 before you run Autoconf(1). Having made the macros available, you must
4203 add a call to the `LTDL_INIT' macro (after the call to `LT_INIT') to
4204 your package's `configure.ac' to perform the configure time checks
4205 required to build the library correctly. Unfortunately, this method
4206 has problems if you then try to link the package binaries with an
4207 installed libltdl, or a library that depends on libltdl, because of the
4208 duplicate symbol definitions. For example, ultimately linking against
4209 two different versions of libltdl, or against both a local convenience
4210 library and an installed libltdl is bad. Ensuring that only one copy
4211 of the libltdl sources are linked into any program is left as an
4212 exercise for the reader.
4214 -- Macro: LT_CONFIG_LTDL_DIR (DIRECTORY)
4215 Declare DIRECTORY to be the location of the `libltdl' source
4216 files, for `libtoolize --ltdl' to place them. *Note Invoking
4217 libtoolize::, for more details. Provided that you add an
4218 appropriate `LT_CONFIG_LTDL_DIR' call in your `configure.ac'
4219 before calling `libtoolize', the appropriate `libltdl' files will
4220 be installed automatically.
4222 -- Macro: LTDL_INIT (OPTIONS)
4223 -- Macro: LT_WITH_LTDL
4224 -- Macro: AC_WITH_LTDL
4225 `AC_WITH_LTDL' and `LT_WITH_LTDL' are deprecated names for older
4226 versions of this macro; `autoupdate' will update your
4227 `configure.ac' file.
4229 This macro adds the following options to the `configure' script:
4231 `--with-ltdl-include INSTALLED-LTDL-HEADER-DIR'
4232 The `LTDL_INIT' macro will look in the standard header file
4233 locations to find the installed `libltdl' headers. If
4234 `LTDL_INIT' can't find them by itself, the person who builds
4235 your package can use this option to tell `configure' where
4236 the installed `libltdl' headers are.
4238 `--with-ltdl-lib INSTALLED-LTDL-LIBRARY-DIR'
4239 Similarly, the person building your package can use this
4240 option to help `configure' find the installed `libltdl.la'.
4242 `--with-included-ltdl'
4243 If there is no installed `libltdl', or in any case if the
4244 person building your package would rather use the `libltdl'
4245 sources shipped with the package in the subdirectory named by
4246 `LT_CONFIG_LTDL_DIR', they should pass this option to
4249 If the `--with-included-ltdl' is not passed at configure time, and
4250 an installed `libltdl' is not found(2), then `configure' will exit
4251 immediately with an error that asks the user to either specify the
4252 location of an installed `libltdl' using the `--with-ltdl-include'
4253 and `--with-ltdl-lib' options, or to build with the `libltdl'
4254 sources shipped with the package by passing `--with-included-ltdl'.
4256 If an installed `libltdl' is found, then `LIBLTDL' is set to the
4257 link flags needed to use it, and `LTDLINCL' to the preprocessor
4258 flags needed to find the installed headers, and `LTDLDEPS' will be
4259 empty. Note, however, that no version checking is performed. You
4260 should manually check for the `libltdl' features you need in
4266 # The lt_dladvise_init symbol was added with libtool-2.2
4267 if test "x$with_included_ltdl" != "xyes"; then
4268 save_CFLAGS="$CFLAGS"
4269 save_LDFLAGS="$LDFLAGS"
4270 CFLAGS="$CFLAGS $LTDLINCL"
4271 LDFLAGS="$LDFLAGS $LIBLTDL"
4272 AC_CHECK_LIB([ltdl], [lt_dladvise_init],
4274 [AC_MSG_ERROR([installed libltdl is too old])])
4275 LDFLAGS="$save_LDFLAGS"
4276 CFLAGS="$save_CFLAGS"
4279 OPTIONS may include no more than one of the following build modes
4280 depending on how you want your project to build `libltdl':
4281 `nonrecursive', `recursive', or `subproject'. In order for
4282 `libtoolize' to detect this option correctly, if you supply one of
4283 these arguments, they must be given literally (i.e., macros or
4284 shell variables that expand to the correct ltdl mode will not
4288 This is how the Libtool project distribution builds the
4289 `libltdl' we ship and install. If you wish to use Automake
4290 to build `libltdl' without invoking a recursive make to
4291 descend into the `libltdl' subdirectory, then use this
4292 option. You will need to set your configuration up carefully
4293 to make this work properly, and you will need releases of
4294 Autoconf and Automake that support `subdir-objects' and
4295 `LIBOBJDIR' properly. In your `configure.ac', add:
4297 AM_INIT_AUTOMAKE([subdir-objects])
4298 AC_CONFIG_HEADERS([config.h])
4299 LT_CONFIG_LTDL_DIR([libltdl])
4301 LTDL_INIT([nonrecursive])
4303 You _have to_ use a config header, but it may have a name
4304 different than `config.h'.
4306 Also, add the following near the top of your `Makefile.am':
4317 noinst_LTLIBRARIES =
4321 include libltdl/Makefile.inc
4323 Unless you build no other libraries from this `Makefile.am',
4324 you will also need to change `lib_LTLIBRARIES' to assign with
4325 `+=' so that the `libltdl' targets declared in `Makefile.inc'
4326 are not overwritten.
4329 This build mode still requires that you use Automake, but (in
4330 contrast with `nonrecursive') uses the more usual device of
4331 starting another `make' process in the `libltdl'
4332 subdirectory. To use this mode, you should add to your
4336 AC_CONFIG_HEADERS([config.h])
4337 LT_CONFIG_LTDL_DIR([libltdl])
4339 LTDL_INIT([recursive])
4340 AC_CONFIG_FILES([libltdl/Makefile])
4342 Again, you _have to_ use a config header, but it may have a
4343 name different than `config.h' if you like.
4345 Also, add this to your `Makefile.am':
4350 This mode is the default unless you explicitly add
4351 `recursive' or `nonrecursive' to your `LTDL_INIT' options;
4352 `subproject' is the only mode supported by previous releases
4353 of libltdl. Even if you do not use Autoconf in the parent
4354 project, then, in `subproject' mode, still `libltdl' contains
4355 all the necessary files to configure and build itself - you
4356 just need to arrange for your build system to call
4357 `libltdl/configure' with appropriate options, and then run
4358 `make' in the `libltdl' subdirectory.
4360 If you _are_ using Autoconf and Automake, then you will need
4361 to add the following to your `configure.ac':
4363 LT_CONFIG_LTDL_DIR([libltdl])
4366 and to `Makefile.am':
4370 Aside from setting the libltdl build mode, there are other keywords
4371 that you can pass to `LTDL_INIT' to modify its behavior when
4372 `--with-included-ltdl' has been given:
4375 This is the default unless you explicitly add `installable' to
4376 your `LTDL_INIT' options.
4378 This keyword will cause options to be passed to the
4379 `configure' script in the subdirectory named by
4380 `LT_CONFIG_LTDL_DIR' in order to cause it to be built as a
4381 convenience library. If you're not using automake, you will
4382 need to define `top_build_prefix', `top_builddir', and
4383 `top_srcdir' in your makefile so that `LIBLTDL', `LTDLDEPS',
4384 and `LTDLINCL' expand correctly.
4386 One advantage of the convenience library is that it is not
4387 installed, so the fact that you use `libltdl' will not be
4388 apparent to the user, and it won't overwrite a pre-installed
4389 version of `libltdl' the system might already have in the
4390 installation directory. On the other hand, if you want to
4391 upgrade `libltdl' for any reason (e.g. a bugfix) you'll have
4392 to recompile your package instead of just replacing the
4393 shared installed version of `libltdl'. However, if your
4394 programs or libraries are linked with other libraries that
4395 use such a pre-installed version of `libltdl', you may get
4396 linker errors or run-time crashes. Another problem is that
4397 you cannot link the convenience library into more than one
4398 libtool library, then link a single program with those
4399 libraries, because you may get duplicate symbols. In general
4400 you can safely use the convenience library in programs that
4401 don't depend on other libraries that might use `libltdl' too.
4404 This keyword will pass options to the `configure' script in
4405 the subdirectory named by `LT_CONFIG_LTDL_DIR' in order to
4406 cause it to be built as an installable library. If you're not
4407 using automake, you will need to define `top_build_prefix',
4408 `top_builddir' and `top_srcdir' in your makefile so that
4409 `LIBLTDL', `LTDLDEPS', and `LTDLINCL' are expanded properly.
4411 Be aware that you could overwrite another `libltdl' already
4412 installed to the same directory if you use this option.
4414 Whatever method you use, `LTDL_INIT' will define the shell variable
4415 LIBLTDL to the link flag that you should use to link with `libltdl',
4416 the shell variable LTDLDEPS to the files that can be used as a
4417 dependency in `Makefile' rules, and the shell variable LTDLINCL to the
4418 preprocessor flag that you should use to compile programs that include
4419 `ltdl.h'. So, when you want to link a program with libltdl, be it a
4420 convenience, installed or installable library, just use `$(LTDLINCL)'
4421 for preprocessing and compilation, and `$(LIBLTDL)' for linking.
4423 * If your package is built using an installed version of `libltdl',
4424 LIBLTDL will be set to the compiler flags needed to link against
4425 the installed library, LTDLDEPS will be empty, and LTDLINCL will
4426 be set to the compiler flags needed to find the `libltdl' header
4429 * If your package is built using the convenience libltdl, LIBLTDL
4430 and LTDLDEPS will be the pathname for the convenience version of
4431 libltdl (starting with `${top_builddir}/' or
4432 `${top_build_prefix}') and LTDLINCL will be `-I' followed by the
4433 directory that contains `ltdl.h' (starting with `${top_srcdir}/').
4435 * If an installable version of the included `libltdl' is being
4436 built, its pathname starting with `${top_builddir}/' or
4437 `${top_build_prefix}', will be stored in LIBLTDL and LTDLDEPS, and
4438 LTDLINCL will be set just like in the case of convenience library.
4440 You should probably also use the `dlopen' option to `LT_INIT' in
4441 your `configure.ac', otherwise libtool will assume no dlopening
4442 mechanism is supported, and revert to dlpreopening, which is probably
4443 not what you want. Avoid using the `-static', `-static-libtool-libs',
4444 or `-all-static' switches when linking programs with libltdl. This
4445 will not work on all platforms, because the dlopening functions may not
4446 be available for static linking.
4448 The following example shows you how to embed an installable libltdl
4449 in your package. In order to use the convenience variant, just replace
4450 the `LTDL_INIT' option `installable' with `convenience'. We assume
4451 that libltdl was embedded using `libtoolize --ltdl'.
4455 # Name the subdirectory that contains libltdl sources
4456 LT_CONFIG_LTDL_DIR([libltdl])
4458 # Configure libtool with dlopen support if possible
4461 # Enable building of the installable libltdl library
4462 LTDL_INIT([installable])
4469 AM_CPPFLAGS = $(LTDLINCL)
4471 myprog_LDFLAGS = -export-dynamic
4472 myprog_LDADD = $(LIBLTDL) -dlopen self -dlopen foo1.la
4473 myprog_DEPENDENCIES = $(LTDLDEPS) foo1.la
4476 -- Macro: LTDL_INSTALLABLE
4477 -- Macro: AC_LIBLTDL_INSTALLABLE
4478 These macros are deprecated, the `installable' option to
4479 `LTDL_INIT' should be used instead.
4481 -- Macro: LTDL_CONVENIENCE
4482 -- Macro: AC_LIBLTDL_CONVENIENCE
4483 These macros are deprecated, the `convenience' option to
4484 `LTDL_INIT' should be used instead.
4486 ---------- Footnotes ----------
4488 (1) We used to recommend adding the contents of `ltdl.m4' to
4489 `acinclude.m4', but with `aclocal' from a modern Automake (1.8 or
4490 newer) and this release of libltdl that is not only unnecessary but
4491 makes it easy to forget to upgrade `acinclude.m4' if you move to a
4492 different release of libltdl.
4494 (2) Even if libltdl is installed, `LTDL_INIT' may fail to detect it
4495 if libltdl depends on symbols provided by libraries other than the C
4499 File: libtool.info, Node: Trace interface, Next: FAQ, Prev: Using libltdl, Up: Top
4501 12 Libtool's trace interface
4502 ****************************
4504 This section describes macros whose sole purpose is to be traced using
4505 Autoconf's `--trace' option (*note The Autoconf Manual:
4506 (autoconf)autoconf Invocation.) to query the Libtool configuration of a
4507 project. These macros are called by Libtool internals and should never
4508 be called by user code; they should only be traced.
4510 -- Macro: LT_SUPPORTED_TAG (TAG)
4511 This macro is called once for each language enabled in the
4512 package. Its only argument, TAG, is the tag-name corresponding to
4513 the language (*note Tags::).
4515 You can therefore retrieve the list of all tags enabled in a
4516 project using the following command:
4517 autoconf --trace 'LT_SUPPORTED_TAG:$1'
4520 File: libtool.info, Node: FAQ, Next: Troubleshooting, Prev: Trace interface, Up: Top
4522 13 Frequently Asked Questions about libtool
4523 *******************************************
4525 This chapter covers some questions that often come up on the mailing
4530 * Stripped link flags:: Dropped flags when creating a library
4533 File: libtool.info, Node: Stripped link flags, Up: FAQ
4535 13.1 Why does libtool strip link flags when creating a library?
4536 ===============================================================
4538 When creating a shared library, but not when compiling or creating a
4539 program, `libtool' drops some flags from the command line provided by
4540 the user. This is done because flags unknown to `libtool' may
4541 interfere with library creation or require additional support from
4542 `libtool', and because omitting flags is usually the conservative
4543 choice for a successful build.
4545 If you encounter flags that you think are useful to pass, as a
4546 work-around you can prepend flags with `-Wc,' or `-Xcompiler ' to allow
4547 them to be passed through to the compiler driver (*note Link mode::).
4548 Another possibility is to add flags already to the compiler command at
4549 `configure' run time:
4551 ./configure CC='gcc -m64'
4553 If you think `libtool' should let some flag through by default,
4554 here's how you can test such an inclusion: grab the Libtool development
4555 tree, edit the `ltmain.m4sh' file in the `libltdl/config' subdirectory
4556 to pass through the flag (search for `Flags to be passed through'),
4557 re-bootstrap and build with the flags in question added to `LDFLAGS',
4558 `CFLAGS', `CXXFLAGS', etc. on the `configure' command line as
4559 appropriate. Run the testsuite as described in the `README' file and
4560 report results to the Libtool bug reporting address
4561 <bug-libtool@gnu.org>.
4564 File: libtool.info, Node: Troubleshooting, Next: Maintaining, Prev: FAQ, Up: Top
4569 Libtool is under constant development, changing to remain up-to-date
4570 with modern operating systems. If libtool doesn't work the way you
4571 think it should on your platform, you should read this chapter to help
4572 determine what the problem is, and how to resolve it.
4576 * Libtool test suite:: Libtool's self-tests.
4577 * Reporting bugs:: How to report problems with libtool.
4580 File: libtool.info, Node: Libtool test suite, Next: Reporting bugs, Up: Troubleshooting
4582 14.1 The libtool test suite
4583 ===========================
4585 Libtool comes with two integrated sets of tests to check that your build
4586 is sane, that test its capabilities, and report obvious bugs in the
4587 libtool program. These tests, too, are constantly evolving, based on
4588 past problems with libtool, and known deficiencies in other operating
4591 As described in the `README' file, you may run `make -k check' after
4592 you have built libtool (possibly before you install it) in order to
4593 make sure that it meets basic functional requirements.
4597 * Test descriptions:: The contents of the old test suite.
4598 * When tests fail:: What to do when a test fails.
4601 File: libtool.info, Node: Test descriptions, Next: When tests fail, Up: Libtool test suite
4603 14.1.1 Description of test suite
4604 --------------------------------
4606 Here is a list of the current programs in the old test suite, and what
4615 These programs check to see that the `tests/cdemo' subdirectory of
4616 the libtool distribution can be configured and built correctly.
4618 The `tests/cdemo' subdirectory contains a demonstration of libtool
4619 convenience libraries, a mechanism that allows build-time static
4620 libraries to be created, in a way that their components can be
4621 later linked into programs or other libraries, even shared ones.
4623 The tests `cdemo-make.test' and `cdemo-exec.test' are executed
4624 three times, under three different libtool configurations:
4625 `cdemo-conf.test' configures `cdemo/libtool' to build both static
4626 and shared libraries (the default for platforms that support
4627 both), `cdemo-static.test' builds only static libraries
4628 (`--disable-shared'), and `cdemo-shared.test' builds only shared
4629 libraries (`--disable-static').
4631 The test `cdemo-undef.test' tests the generation of shared
4632 libraries with undefined symbols on systems that allow this.
4644 These programs check to see that the `tests/demo' subdirectory of
4645 the libtool distribution can be configured, built, installed, and
4646 uninstalled correctly.
4648 The `tests/demo' subdirectory contains a demonstration of a trivial
4649 package that uses libtool. The tests `demo-make.test',
4650 `demo-exec.test', `demo-inst.test' and `demo-unst.test' are
4651 executed four times, under four different libtool configurations:
4652 `demo-conf.test' configures `demo/libtool' to build both static
4653 and shared libraries, `demo-static.test' builds only static
4654 libraries (`--disable-shared'), and `demo-shared.test' builds only
4655 shared libraries (`--disable-static'). `demo-nofast.test'
4656 configures `demo/libtool' to disable the fast-install mode
4657 (`--enable-fast-install=no'). `demo-pic.test' configures
4658 `demo/libtool' to prefer building PIC code (`--with-pic'),
4659 `demo-nopic.test' to prefer non-PIC code (`--without-pic').
4662 Many systems cannot link static libraries into shared libraries.
4663 libtool uses a `deplibs_check_method' to prevent such cases. This
4664 tests checks whether libtool's `deplibs_check_method' works
4667 `demo-hardcode.test'
4668 On all systems with shared libraries, the location of the library
4669 can be encoded in executables that are linked against it *note
4670 Linking executables::. This test checks the conditions under
4671 which your system linker hardcodes the library location, and
4672 guarantees that they correspond to libtool's own notion of how
4673 your linker behaves.
4676 `depdemo-relink.test'
4677 These tests check whether variable SHLIBPATH_OVERRIDES_RUNPATH is
4678 properly set. If the test fails and VERBOSE is set, it will
4679 indicate what the variable should have been set to.
4681 `demo-noinst-link.test'
4682 Checks whether libtool will not try to link with a previously
4683 installed version of a library when it should be linking with a
4691 `depdemo-static.test'
4692 `depdemo-shared.test'
4693 `depdemo-nofast.test'
4694 These programs check to see that the `tests/depdemo' subdirectory
4695 of the libtool distribution can be configured, built, installed,
4696 and uninstalled correctly.
4698 The `tests/depdemo' subdirectory contains a demonstration of
4699 inter-library dependencies with libtool. The test programs link
4700 some interdependent libraries.
4702 The tests `depdemo-make.test', `depdemo-exec.test',
4703 `depdemo-inst.test' and `depdemo-unst.test' are executed four
4704 times, under four different libtool configurations:
4705 `depdemo-conf.test' configures `depdemo/libtool' to build both
4706 static and shared libraries, `depdemo-static.test' builds only
4707 static libraries (`--disable-shared'), and `depdemo-shared.test'
4708 builds only shared libraries (`--disable-static').
4709 `depdemo-nofast.test' configures `depdemo/libtool' to disable the
4710 fast-install mode (`--enable-fast-install=no').
4719 These programs check to see that the `tests/mdemo' subdirectory of
4720 the libtool distribution can be configured, built, installed, and
4721 uninstalled correctly.
4723 The `tests/mdemo' subdirectory contains a demonstration of a
4724 package that uses libtool and the system independent dlopen wrapper
4725 `libltdl' to load modules. The library `libltdl' provides a
4726 dlopen wrapper for various platforms (Linux, Solaris, HP/UX etc.)
4727 including support for dlpreopened modules (*note Dlpreopening::).
4729 The tests `mdemo-make.test', `mdemo-exec.test', `mdemo-inst.test'
4730 and `mdemo-unst.test' are executed three times, under three
4731 different libtool configurations: `mdemo-conf.test' configures
4732 `mdemo/libtool' to build both static and shared libraries,
4733 `mdemo-static.test' builds only static libraries
4734 (`--disable-shared'), and `mdemo-shared.test' builds only shared
4735 libraries (`--disable-static').
4738 This test checks whether libtool's `--dry-run' mode works properly.
4743 These programs check to see that the `tests/mdemo2' subdirectory of
4744 the libtool distribution can be configured, built, and executed
4747 The `tests/mdemo2' directory contains a demonstration of a package
4748 that attempts to link with a library (from the `tests/mdemo'
4749 directory) that itself does dlopening of libtool modules.
4752 This test guarantees that linking directly against a non-libtool
4753 static library works properly.
4756 This test makes sure that files ending in `.lo' are never linked
4757 directly into a program file.
4760 Check whether we can actually get help for libtool.
4763 Check that a nonexistent objectlist file is properly detected.
4769 These programs check to see that the `tests/pdemo' subdirectory of
4770 the libtool distribution can be configured, built, and executed
4773 The `pdemo-conf.test' lowers the MAX_CMD_LEN variable in the
4774 generated libtool script to test the measures to evade command line
4778 This program checks libtool's metacharacter quoting.
4781 Checks for some nonportable or dubious or undesired shell
4782 constructs in shell scripts.
4785 When other programming languages are used with libtool (*note
4786 Other languages::), the source files may end in suffixes other
4787 than `.c'. This test validates that libtool can handle suffixes
4788 for all the file types that it supports, and that it fails when
4789 the suffix is invalid.
4794 `tagdemo-static.test'
4795 `tagdemo-shared.test'
4796 `tagdemo-undef.test'
4797 These programs check to see that the `tests/tagdemo' subdirectory
4798 of the libtool distribution can be configured, built, and executed
4801 The `tests/tagdemo' directory contains a demonstration of a package
4802 that uses libtool's multi-language support through configuration
4803 tags. It generates a library from C++ sources, which is then
4804 linked to a C++ program.
4809 `f77demo-static.test'
4810 `f77demo-shared.test'
4811 These programs check to see that the `tests/f77demo' subdirectory
4812 of the libtool distribution can be configured, built, and executed
4815 The `tests/f77demo' tests test Fortran 77 support in libtool by
4816 creating libraries from Fortran 77 sources, and mixed Fortran and C
4817 sources, and a Fortran 77 program to use the former library, and a
4818 C program to use the latter library.
4823 `fcdemo-static.test'
4824 `fcdemo-shared.test'
4825 These programs check to see that the `tests/fcdemo' subdirectory
4826 of the libtool distribution can be configured, built, and executed
4829 The `tests/fcdemo' is similar to the `tests/f77demo' directory,
4830 except that Fortran 90 is used in combination with the `FC'
4831 interface provided by Autoconf and Automake.
4834 The new, Autotest-based test suite uses keywords to classify certain
4841 The test group exercises one of these `libtool' language tags.
4845 These keywords denote that the respective external program is
4846 needed by the test group. The tests are typically skipped if the
4847 program is not installed. The `automake' keyword may also denote
4848 use of the `aclocal' program.
4851 This test group may require user interaction on some systems.
4852 Typically, this means closing a popup window about a DLL load
4856 Denote that the `libltdl' library is exercised by the test group.
4860 Denote that the `libtool' or `libtoolize' scripts are exercised by
4861 the test group, respectively.
4864 Denote that this test group may recursively re-invoke the test
4865 suite itself, with changed settings and maybe a changed `libtool'
4866 script. You may use the `INNER_TESTSUITEFLAGS' variable to pass
4867 additional settings to this recursive invocation. Typically,
4868 recursive invocations delimit the set of tests with another
4869 keyword, for example by passing `-k libtool' right before the
4870 expansion of the `INNER_TESTSUITEFLAGS' variable (without an
4871 intervening space, so you get the chance for further delimitation).
4873 Test groups with the keyword `recursive' should not be denoted with
4874 keywords, in order to avoid infinite recursion. As a consequence,
4875 recursive test groups themselves should never require user
4876 interaction, while the test groups they invoke may do so.
4878 For example, in order to avoid any interactive test groups, you could
4882 TESTSUITEFLAGS='-k !interactive INNER_TESTSUITEFLAGS=",!interactive"'
4884 while to run only those test groups, you would use this:
4887 TESTSUITEFLAGS='-k interactive -k recursive INNER_TESTSUITEFLAGS=,interactive'
4889 but the convenience targets `check-interactive' and
4890 `check-noninteractive' avoid needing to remember these complex
4891 commands, in addition to also disabling interactive tests in the old
4895 File: libtool.info, Node: When tests fail, Prev: Test descriptions, Up: Libtool test suite
4897 14.1.2 When tests fail
4898 ----------------------
4900 Each of the tests in the old test suite are designed to produce no
4901 output when they are run via `make check'. The exit status of each
4902 program tells the `Makefile' whether or not the test succeeded.
4904 If a test fails, it means that there is either a programming error in
4905 libtool, or in the test program itself.
4907 To investigate a particular test, you may run it directly, as you
4908 would a normal program. When the test is invoked in this way, it
4909 produces output that may be useful in determining what the problem is.
4911 Another way to have the test programs produce output is to set the
4912 VERBOSE environment variable to `yes' before running them. For
4913 example, `env VERBOSE=yes make check' runs all the tests, and has each
4914 of them display debugging information.
4916 The new, Autotest-based test suite produces as output a file
4917 `tests/testsuite.log' which contains information about failed tests.
4919 You can pass options to the test suite through the `make' variable
4920 TESTSUITEFLAGS (*note The Autoconf Manual: (autoconf)testsuite
4924 File: libtool.info, Node: Reporting bugs, Prev: Libtool test suite, Up: Troubleshooting
4929 If you think you have discovered a bug in libtool, you should think
4930 twice: the libtool maintainer is notorious for passing the buck (or
4931 maybe that should be "passing the bug"). Libtool was invented to fix
4932 known deficiencies in shared library implementations, so, in a way, most
4933 of the bugs in libtool are actually bugs in other operating systems.
4934 However, the libtool maintainer would definitely be happy to add support
4935 for somebody else's buggy operating system. [I wish there was a good
4936 way to do winking smiley-faces in Texinfo.]
4938 Genuine bugs in libtool include problems with shell script
4939 portability, documentation errors, and failures in the test suite
4940 (*note Libtool test suite::).
4942 First, check the documentation and help screens to make sure that the
4943 behaviour you think is a problem is not already mentioned as a feature.
4945 Then, you should read the Emacs guide to reporting bugs (*note
4946 Reporting Bugs: (emacs)Bugs.). Some of the details listed there are
4947 specific to Emacs, but the principle behind them is a general one.
4949 Finally, send a bug report to the Libtool bug reporting address
4950 <bug-libtool@gnu.org> with any appropriate _facts_, such as test suite
4951 output (*note When tests fail::), all the details needed to reproduce
4952 the bug, and a brief description of why you think the behaviour is a
4953 bug. Be sure to include the word "libtool" in the subject line, as
4954 well as the version number you are using (which can be found by typing
4955 `libtool --version').
4958 File: libtool.info, Node: Maintaining, Next: GNU Free Documentation License, Prev: Troubleshooting, Up: Top
4960 15 Maintenance notes for libtool
4961 ********************************
4963 This chapter contains information that the libtool maintainer finds
4964 important. It will be of no use to you unless you are considering
4965 porting libtool to new systems, or writing your own libtool.
4969 * New ports:: How to port libtool to new systems.
4970 * Tested platforms:: When libtool was last tested.
4971 * Platform quirks:: Information about different library systems.
4972 * libtool script contents:: Configuration information that libtool uses.
4973 * Cheap tricks:: Making libtool maintainership easier.
4976 File: libtool.info, Node: New ports, Next: Tested platforms, Up: Maintaining
4978 15.1 Porting libtool to new systems
4979 ===================================
4981 Before you embark on porting libtool to an unsupported system, it is
4982 worthwhile to send e-mail to the Libtool mailing list
4983 <libtool@gnu.org>, to make sure that you are not duplicating existing
4986 If you find that any porting documentation is missing, please
4987 complain! Complaints with patches and improvements to the
4988 documentation, or to libtool itself, are more than welcome.
4992 * Information sources:: Where to find relevant documentation
4993 * Porting inter-library dependencies:: Implementation details explained
4996 File: libtool.info, Node: Information sources, Next: Porting inter-library dependencies, Up: New ports
4998 15.1.1 Information sources
4999 --------------------------
5001 Once it is clear that a new port is necessary, you'll generally need the
5002 following information:
5004 canonical system name
5005 You need the output of `config.guess' for this system, so that you
5006 can make changes to the libtool configuration process without
5007 affecting other systems.
5009 man pages for `ld' and `cc'
5010 These generally describe what flags are used to generate PIC, to
5011 create shared libraries, and to link against only static
5012 libraries. You may need to follow some cross references to find
5013 the information that is required.
5015 man pages for `ld.so', `rtld', or equivalent
5016 These are a valuable resource for understanding how shared
5017 libraries are loaded on the system.
5019 man page for `ldconfig', or equivalent
5020 This page usually describes how to install shared libraries.
5022 output from `ls -l /lib /usr/lib'
5023 This shows the naming convention for shared libraries on the
5024 system, including which names should be symbolic links.
5026 any additional documentation
5027 Some systems have special documentation on how to build and install
5030 If you know how to program the Bourne shell, then you can complete
5031 the port yourself; otherwise, you'll have to find somebody with the
5032 relevant skills who will do the work. People on the libtool mailing
5033 list are usually willing to volunteer to help you with new ports, so
5034 you can send the information to them.
5036 To do the port yourself, you'll definitely need to modify the
5037 `libtool.m4' macros in order to make platform-specific changes to the
5038 configuration process. You should search that file for the `PORTME'
5039 keyword, which will give you some hints on what you'll need to change.
5040 In general, all that is involved is modifying the appropriate
5041 configuration variables (*note libtool script contents::).
5043 Your best bet is to find an already-supported system that is similar
5044 to yours, and make your changes based on that. In some cases, however,
5045 your system will differ significantly from every other supported system,
5046 and it may be necessary to add new configuration variables, and modify
5047 the `ltmain.in' script accordingly. Be sure to write to the mailing
5048 list before you make changes to `ltmain.in', since they may have advice
5049 on the most effective way of accomplishing what you want.
5052 File: libtool.info, Node: Porting inter-library dependencies, Prev: Information sources, Up: New ports
5054 15.1.2 Porting inter-library dependencies support
5055 -------------------------------------------------
5057 Since version 1.2c, libtool has re-introduced the ability to do
5058 inter-library dependency on some platforms, thanks to a patch by Toshio
5059 Kuratomi <badger@prtr-13.ucsc.edu>. Here's a shortened version of the
5060 message that contained his patch:
5062 The basic architecture is this: in `libtool.m4', the person who
5063 writes libtool makes sure `$deplibs' is included in `$archive_cmds'
5064 somewhere and also sets the variable `$deplibs_check_method', and maybe
5065 `$file_magic_cmd' when `deplibs_check_method' is file_magic.
5067 `deplibs_check_method' can be one of five things:
5068 `file_magic [REGEX]'
5069 looks in the library link path for libraries that have the right
5070 libname. Then it runs `$file_magic_cmd' on the library and checks
5071 for a match against the extended regular expression REGEX. When
5072 FILE_MAGIC_TEST_FILE is set by `libtool.m4', it is used as an
5073 argument to `$file_magic_cmd' in order to verify whether the
5074 regular expression matches its output, and warn the user otherwise.
5077 just checks whether it is possible to link a program out of a list
5078 of libraries, and checks which of those are listed in the output of
5079 `ldd'. It is currently unused, and will probably be dropped in the
5083 will pass everything without any checking. This may work on
5084 platforms in which code is position-independent by default and
5085 inter-library dependencies are properly supported by the dynamic
5086 linker, for example, on DEC OSF/1 3 and 4.
5089 It causes deplibs to be reassigned `deplibs=""'. That way
5090 `archive_cmds' can contain deplibs on all platforms, but not have
5091 deplibs used unless needed.
5094 is the default for all systems unless overridden in `libtool.m4'.
5095 It is the same as `none', but it documents that we really don't
5096 know what the correct value should be, and we welcome patches that
5099 Then in `ltmain.in' we have the real workhorse: a little
5100 initialization and postprocessing (to setup/release variables for use
5101 with eval echo libname_spec etc.) and a case statement that decides the
5102 method that is being used. This is the real code... I wish I could
5103 condense it a little more, but I don't think I can without function
5104 calls. I've mostly optimized it (moved things out of loops, etc.) but
5105 there is probably some fat left. I thought I should stop while I was
5106 ahead, work on whatever bugs you discover, etc. before thinking about
5107 more than obvious optimizations.
5110 File: libtool.info, Node: Tested platforms, Next: Platform quirks, Prev: New ports, Up: Maintaining
5112 15.2 Tested platforms
5113 =====================
5115 This table describes when libtool was last known to be tested on
5116 platforms where it claims to support shared libraries:
5118 -------------------------------------------------------
5119 canonical host name compiler libtool results
5120 (tools versions) release
5121 -------------------------------------------------------
5122 alpha-dec-osf5.1 cc 1.3e ok (1.910)
5123 alpha-dec-osf4.0f gcc 1.3e ok (1.910)
5124 alpha-dec-osf4.0f cc 1.3e ok (1.910)
5125 alpha-dec-osf3.2 gcc 0.8 ok
5126 alpha-dec-osf3.2 cc 0.8 ok
5127 alpha-dec-osf2.1 gcc 1.2f NS
5128 alpha*-unknown-linux-gnu gcc 1.3b ok
5129 (egcs-1.1.2, GNU ld 2.9.1.0.23)
5130 hppa2.0w-hp-hpux11.00 cc 1.2f ok
5131 hppa2.0-hp-hpux10.20 cc 1.3.2 ok
5132 hppa1.1-hp-hpux10.20 gcc 1.2f ok
5133 hppa1.1-hp-hpux10.20 cc 1.3c ok (1.821)
5134 hppa1.1-hp-hpux10.10 gcc 1.2f ok
5135 hppa1.1-hp-hpux10.10 cc 1.2f ok
5136 hppa1.1-hp-hpux9.07 gcc 1.2f ok
5137 hppa1.1-hp-hpux9.07 cc 1.2f ok
5138 hppa1.1-hp-hpux9.05 gcc 1.2f ok
5139 hppa1.1-hp-hpux9.05 cc 1.2f ok
5140 hppa1.1-hp-hpux9.01 gcc 1.2f ok
5141 hppa1.1-hp-hpux9.01 cc 1.2f ok
5142 i*86-*-beos gcc 1.2f ok
5143 i*86-*-bsdi4.0.1 gcc 1.3c ok
5145 i*86-*-bsdi4.0 gcc 1.2f ok
5146 i*86-*-bsdi3.1 gcc 1.2e NS
5147 i*86-*-bsdi3.0 gcc 1.2e NS
5148 i*86-*-bsdi2.1 gcc 1.2e NS
5149 i*86-pc-cygwin gcc 1.3b NS
5150 (egcs-1.1 stock b20.1 compiler)
5151 i*86-*-dguxR4.20MU01 gcc 1.2 ok
5152 i*86-*-freebsd4.3 gcc 1.3e ok (1.912)
5153 i*86-*-freebsdelf4.0 gcc 1.3c ok
5155 i*86-*-freebsdelf3.2 gcc 1.3c ok
5157 i*86-*-freebsdelf3.1 gcc 1.3c ok
5159 i*86-*-freebsdelf3.0 gcc 1.3c ok
5160 i*86-*-freebsd3.0 gcc 1.2e ok
5161 i*86-*-freebsd2.2.8 gcc 1.3c ok
5163 i*86-*-freebsd2.2.6 gcc 1.3b ok
5164 (egcs-1.1 & gcc-2.7.2.1, native ld)
5165 i*86-*-freebsd2.1.5 gcc 0.5 ok
5166 i*86-*-netbsd1.5 gcc 1.3e ok (1.901)
5168 i*86-*-netbsd1.4 gcc 1.3c ok
5170 i*86-*-netbsd1.4.3A gcc 1.3e ok (1.901)
5171 i*86-*-netbsd1.3.3 gcc 1.3c ok
5173 i*86-*-netbsd1.3.2 gcc 1.2e ok
5174 i*86-*-netbsd1.3I gcc 1.2e ok
5176 i*86-*-netbsd1.2 gcc 0.9g ok
5177 i*86-*-linux-gnu gcc 1.3e ok (1.901)
5178 (Red Hat 7.0, gcc "2.96")
5179 i*86-*-linux-gnu gcc 1.3e ok (1.911)
5180 (SuSE 7.0, gcc 2.95.2)
5181 i*86-*-linux-gnulibc1 gcc 1.2f ok
5182 i*86-*-openbsd2.5 gcc 1.3c ok
5184 i*86-*-openbsd2.4 gcc 1.3c ok
5186 i*86-*-solaris2.7 gcc 1.3b ok
5187 (egcs-1.1.2, native ld)
5188 i*86-*-solaris2.6 gcc 1.2f ok
5189 i*86-*-solaris2.5.1 gcc 1.2f ok
5190 i*86-ncr-sysv4.3.03 gcc 1.2f ok
5191 i*86-ncr-sysv4.3.03 cc 1.2e ok
5193 i*86-pc-sco3.2v5.0.5 cc 1.3c ok
5194 i*86-pc-sco3.2v5.0.5 gcc 1.3c ok
5196 i*86-pc-sco3.2v5.0.5 gcc 1.3c ok
5198 i*86-sco-sysv5uw7.1.1 gcc 1.3e ok (1.901)
5199 (gcc-2.95.2, SCO linker)
5200 i*86-UnixWare7.1.0-sysv5 cc 1.3c ok
5201 i*86-UnixWare7.1.0-sysv5 gcc 1.3c ok
5203 m68k-next-nextstep3 gcc 1.2f NS
5204 m68k-sun-sunos4.1.1 gcc 1.2f NS
5206 m88k-dg-dguxR4.12TMU01 gcc 1.2 ok
5207 m88k-motorola-sysv4 gcc 1.3 ok
5209 mips-sgi-irix6.5 gcc 1.2f ok
5211 mips-sgi-irix6.4 gcc 1.2f ok
5212 mips-sgi-irix6.3 gcc 1.3b ok
5213 (egcs-1.1.2, native ld)
5214 mips-sgi-irix6.3 cc 1.3b ok
5216 mips-sgi-irix6.2 gcc 1.2f ok
5217 mips-sgi-irix6.2 cc 0.9 ok
5218 mips-sgi-irix5.3 gcc 1.2f ok
5220 mips-sgi-irix5.3 gcc 1.2f NS
5222 mips-sgi-irix5.3 cc 0.8 ok
5223 mips-sgi-irix5.2 gcc 1.3b ok
5224 (egcs-1.1.2, native ld)
5225 mips-sgi-irix5.2 cc 1.3b ok
5227 mips-sni-sysv4 cc 1.3.5 ok
5228 (Siemens C-compiler)
5229 mips-sni-sysv4 gcc 1.3.5 ok
5230 (gcc-2.7.2.3, GNU assembler 2.8.1, native ld)
5231 mipsel-unknown-openbsd2.1 gcc 1.0 ok
5232 powerpc-apple-darwin6.4 gcc 1.5 ok
5233 (apple dev tools released 12/2002)
5234 powerpc-ibm-aix4.3.1.0 gcc 1.2f ok
5236 powerpc-ibm-aix4.2.1.0 gcc 1.2f ok
5238 powerpc-ibm-aix4.1.5.0 gcc 1.2f ok
5240 powerpc-ibm-aix4.1.5.0 gcc 1.2f NS
5242 powerpc-ibm-aix4.1.4.0 gcc 1.0 ok
5243 powerpc-ibm-aix4.1.4.0 xlc 1.0i ok
5244 rs6000-ibm-aix4.1.5.0 gcc 1.2f ok
5246 rs6000-ibm-aix4.1.4.0 gcc 1.2f ok
5248 rs6000-ibm-aix3.2.5 gcc 1.0i ok
5249 rs6000-ibm-aix3.2.5 xlc 1.0i ok
5250 sparc-sun-solaris2.8 gcc 1.3e ok (1.913)
5251 (gcc-2.95.3 & native ld)
5252 sparc-sun-solaris2.7 gcc 1.3e ok (1.913)
5253 (gcc-2.95.3 & native ld)
5254 sparc-sun-solaris2.6 gcc 1.3e ok (1.913)
5255 (gcc-2.95.3 & native ld)
5256 sparc-sun-solaris2.5.1 gcc 1.3e ok (1.911)
5257 sparc-sun-solaris2.5 gcc 1.3b ok
5258 (egcs-1.1.2, GNU ld 2.9.1 & native ld)
5259 sparc-sun-solaris2.5 cc 1.3b ok
5261 sparc-sun-solaris2.4 gcc 1.0a ok
5262 sparc-sun-solaris2.4 cc 1.0a ok
5263 sparc-sun-solaris2.3 gcc 1.2f ok
5264 sparc-sun-sunos4.1.4 gcc 1.2f ok
5265 sparc-sun-sunos4.1.4 cc 1.0f ok
5266 sparc-sun-sunos4.1.3_U1 gcc 1.2f ok
5267 sparc-sun-sunos4.1.3C gcc 1.2f ok
5268 sparc-sun-sunos4.1.3 gcc 1.3b ok
5269 (egcs-1.1.2, GNU ld 2.9.1 & native ld)
5270 sparc-sun-sunos4.1.3 cc 1.3b ok
5271 sparc-unknown-bsdi4.0 gcc 1.2c ok
5272 sparc-unknown-linux-gnulibc1 gcc 1.2f ok
5273 sparc-unknown-linux-gnu gcc 1.3b ok
5274 (egcs-1.1.2, GNU ld 2.9.1.0.23)
5275 sparc64-unknown-linux-gnu gcc 1.2f ok
5278 - "ok" means "all tests passed".
5279 - "NS" means "Not Shared", but OK for static libraries
5281 Note: The vendor-distributed HP-UX `sed'(1) programs are horribly
5282 broken, and cannot handle libtool's requirements, so users may report
5283 unusual problems. There is no workaround except to install a working
5284 `sed' (such as GNU `sed') on these systems.
5286 Note: The vendor-distributed NCR MP-RAS `cc' programs emits
5287 copyright on standard error that confuse tests on size of
5288 `conftest.err'. The workaround is to specify `CC' when run `configure'
5289 with `CC='cc -Hnocopyr''.
5292 File: libtool.info, Node: Platform quirks, Next: libtool script contents, Prev: Tested platforms, Up: Maintaining
5294 15.3 Platform quirks
5295 ====================
5297 This section is dedicated to the sanity of the libtool maintainers. It
5298 describes the programs that libtool uses, how they vary from system to
5299 system, and how to test for them.
5301 Because libtool is a shell script, it can be difficult to understand
5302 just by reading it from top to bottom. This section helps show why
5303 libtool does things a certain way. Combined with the scripts
5304 themselves, you should have a better sense of how to improve libtool, or
5309 * References:: Finding more information.
5310 * Compilers:: Creating object files from source files.
5311 * Reloadable objects:: Binding object files together.
5312 * Multiple dependencies:: Removing duplicate dependent libraries.
5313 * Archivers:: Programs that create static archives.
5316 File: libtool.info, Node: References, Next: Compilers, Up: Platform quirks
5321 The following is a list of valuable documentation references:
5323 * SGI's IRIX Manual Pages can be found at
5324 `http://techpubs.sgi.com/cgi-bin/infosrch.cgi?cmd=browse&db=man'.
5326 * Sun's free service area
5327 (`http://www.sun.com/service/online/free.html') and documentation
5328 server (`http://docs.sun.com/').
5330 * Compaq's Tru64 UNIX online documentation is at
5331 (`http://tru64unix.compaq.com/faqs/publications/pub_page/doc_list.html')
5332 with C++ documentation at
5333 (`http://tru64unix.compaq.com/cplus/docs/index.htm').
5335 * Hewlett-Packard has online documentation at
5336 (`http://docs.hp.com/index.html').
5338 * IBM has online documentation at
5339 (`http://www.rs6000.ibm.com/resource/aix_resource/Pubs/').
5342 File: libtool.info, Node: Compilers, Next: Reloadable objects, Prev: References, Up: Platform quirks
5347 The only compiler characteristics that affect libtool are the flags
5348 needed (if any) to generate PIC objects. In general, if a C compiler
5349 supports certain PIC flags, then any derivative compilers support the
5350 same flags. Until there are some noteworthy exceptions to this rule,
5351 this section will document only C compilers.
5353 The following C compilers have standard command line options,
5354 regardless of the platform:
5357 This is the GNU C compiler, which is also the system compiler for
5358 many free operating systems (FreeBSD, GNU/Hurd, GNU/Linux, Lites,
5359 NetBSD, and OpenBSD, to name a few).
5361 The `-fpic' or `-fPIC' flags can be used to generate
5362 position-independent code. `-fPIC' is guaranteed to generate
5363 working code, but the code is slower on m68k, m88k, and Sparc
5364 chips. However, using `-fpic' on those chips imposes arbitrary
5365 size limits on the shared libraries.
5367 The rest of this subsection lists compilers by the operating system
5368 that they are bundled with:
5372 Most AIX compilers have no PIC flags, since AIX (with the
5373 exception of AIX for IA-64) runs on PowerPC and RS/6000 chips. (1)
5376 Use `+Z' to generate PIC.
5379 Digital/UNIX 3.x does not have PIC flags, at least not on the
5383 Use `-KPIC' to generate PIC.
5386 Use `-PIC' to generate PIC.
5388 ---------- Footnotes ----------
5390 (1) All code compiled for the PowerPC and RS/6000 chips
5391 (`powerpc-*-*', `powerpcle-*-*', and `rs6000-*-*') is
5392 position-independent, regardless of the operating system or compiler
5393 suite. So, "regular objects" can be used to build shared libraries on
5394 these systems and no special PIC compiler flags are required.
5397 File: libtool.info, Node: Reloadable objects, Next: Multiple dependencies, Prev: Compilers, Up: Platform quirks
5399 15.3.3 Reloadable objects
5400 -------------------------
5402 On all known systems, a reloadable object can be created by running `ld
5403 -r -o OUTPUT.o INPUT1.o INPUT2.o'. This reloadable object may be
5404 treated as exactly equivalent to other objects.
5407 File: libtool.info, Node: Multiple dependencies, Next: Archivers, Prev: Reloadable objects, Up: Platform quirks
5409 15.3.4 Multiple dependencies
5410 ----------------------------
5412 On most modern platforms the order in which dependent libraries are
5413 listed has no effect on object generation. In theory, there are
5414 platforms that require libraries that provide missing symbols to other
5415 libraries to be listed after those libraries whose symbols they provide.
5417 Particularly, if a pair of static archives each resolve some of the
5418 other's symbols, it might be necessary to list one of those archives
5419 both before and after the other one. Libtool does not currently cope
5420 with this situation well, since duplicate libraries are removed from
5421 the link line by default. Libtool provides the command line option
5422 `--preserve-dup-deps' to preserve all duplicate dependencies in cases
5423 where it is necessary.
5426 File: libtool.info, Node: Archivers, Prev: Multiple dependencies, Up: Platform quirks
5431 On all known systems, building a static library can be accomplished by
5432 running `ar cru libNAME.a OBJ1.o OBJ2.o ...', where the `.a' file is
5433 the output library, and each `.o' file is an object file.
5435 On all known systems, if there is a program named `ranlib', then it
5436 must be used to "bless" the created library before linking against it,
5437 with the `ranlib libNAME.a' command. Some systems, like Irix, use the
5438 `ar ts' command, instead.
5441 File: libtool.info, Node: libtool script contents, Next: Cheap tricks, Prev: Platform quirks, Up: Maintaining
5443 15.4 `libtool' script contents
5444 ==============================
5446 Since version 1.4, the `libtool' script is generated by `configure'
5447 (*note Configuring::). In earlier versions, `configure' achieved this
5448 by calling a helper script called `ltconfig'. From libtool version 0.7
5449 to 1.0, this script simply set shell variables, then sourced the
5450 libtool backend, `ltmain.sh'. `ltconfig' from libtool version 1.1
5451 through 1.3 inlined the contents of `ltmain.sh' into the generated
5452 `libtool', which improved performance on many systems. The tests that
5453 `ltconfig' used to perform are now kept in `libtool.m4' where they can
5454 be written using Autoconf. This has the runtime performance benefits
5455 of inlined `ltmain.sh', _and_ improves the build time a little while
5456 considerably easing the amount of raw shell code that used to need
5459 The convention used for naming variables that hold shell commands for
5460 delayed evaluation, is to use the suffix `_cmd' where a single line of
5461 valid shell script is needed, and the suffix `_cmds' where multiple
5462 lines of shell script *may* be delayed for later evaluation. By
5463 convention, `_cmds' variables delimit the evaluation units with the `~'
5464 character where necessary.
5466 Here is a listing of each of the configuration variables, and how
5467 they are used within `ltmain.sh' (*note Configuring::):
5470 The name of the system library archiver.
5473 The name of the compiler used to configure libtool. This will
5474 always contain the compiler for the current language (*note
5478 An `echo' program that does not interpret backslashes as an escape
5479 character. It may be given only one argument, so due quoting is
5483 The name of the linker that libtool should use internally for
5484 reloadable linking and possibly shared libraries.
5487 -- Variable: LTCFLAGS
5488 The name of the C compiler and C compiler flags used to configure
5492 The name of a BSD- or MS-compatible program that produces listings
5493 of global symbols. For BSD `nm', the symbols should be in one the
5496 ADDRESS C GLOBAL-VARIABLE-NAME
5497 ADDRESS D GLOBAL-VARIABLE-NAME
5498 ADDRESS T GLOBAL-FUNCTION-NAME
5500 For MS `dumpbin', the symbols should be in one of the following
5503 COUNTER SIZE UNDEF notype External | GLOBAL-VAR
5504 COUNTER ADDRESS SECTION notype External | GLOBAL-VAR
5505 COUNTER ADDRESS SECTION notype () External | GLOBAL-FUNC
5507 The SIZE of the global variables are not zero and the SECTION of
5508 the global functions are not "UNDEF". Symbols in "pick any"
5509 sections ("pick any" appears in the section header) are not global
5513 Set to the name of the `ranlib' program, if any.
5515 -- Variable: allow_undefined_flag
5516 The flag that is used by `archive_cmds' in order to declare that
5517 there will be unresolved symbols in the resulting shared library.
5518 Empty, if no such flag is required. Set to `unsupported' if there
5519 is no way to generate a shared library with references to symbols
5520 that aren't defined in that library.
5522 -- Variable: always_export_symbols
5523 Whether libtool should automatically generate a list of exported
5524 symbols using EXPORT_SYMBOLS_CMDS before linking an archive. Set
5525 to `yes' or `no'. Default is `no'.
5527 -- Variable: archive_cmds
5528 -- Variable: archive_expsym_cmds
5529 -- Variable: old_archive_cmds
5530 Commands used to create shared libraries, shared libraries with
5531 `-export-symbols' and static libraries, respectively.
5533 -- Variable: old_archive_from_new_cmds
5534 If the shared library depends on a static library,
5535 `old_archive_from_new_cmds' contains the commands used to create
5536 that static library. If this variable is not empty,
5537 `old_archive_cmds' is not used.
5539 -- Variable: old_archive_from_expsyms_cmds
5540 If a static library must be created from the export symbol list in
5541 order to correctly link with a shared library,
5542 `old_archive_from_expsyms_cmds' contains the commands needed to
5543 create that static library. When these commands are executed, the
5544 variable SONAME contains the name of the shared library in
5545 question, and the $OBJDIR/$NEWLIB contains the path of the static
5546 library these commands should build. After executing these
5547 commands, libtool will proceed to link against $OBJDIR/$NEWLIB
5550 -- Variable: lock_old_archive_extraction
5551 Set to `yes' if the extraction of a static library requires locking
5552 the library file. This is required on Darwin.
5555 -- Variable: build_alias
5556 -- Variable: build_os
5557 Set to the specified and canonical names of the system that
5558 libtool was built on.
5560 -- Variable: build_libtool_libs
5561 Whether libtool should build shared libraries on this system. Set
5564 -- Variable: build_old_libs
5565 Whether libtool should build static libraries on this system. Set
5568 -- Variable: compiler_c_o
5569 Whether the compiler supports the `-c' and `-o' options
5570 simultaneously. Set to `yes' or `no'.
5572 -- Variable: compiler_needs_object
5573 Whether the compiler has to see an object listed on the command
5574 line in order to successfully invoke the linker. If `no', then a
5575 set of convenience archives or a set of object file names can be
5576 passed via linker-specific options or linker scripts.
5578 -- Variable: dlopen_support
5579 Whether `dlopen' is supported on the platform. Set to `yes' or
5582 -- Variable: dlopen_self
5583 Whether it is possible to `dlopen' the executable itself. Set to
5586 -- Variable: dlopen_self_static
5587 Whether it is possible to `dlopen' the executable itself, when it
5588 is linked statically (`-all-static'). Set to `yes' or `no'.
5590 -- Variable: exclude_expsyms
5591 List of symbols that should not be listed in the preloaded symbols.
5593 -- Variable: export_dynamic_flag_spec
5594 Compiler link flag that allows a dlopened shared library to
5595 reference symbols that are defined in the program.
5597 -- Variable: export_symbols_cmds
5598 Commands to extract exported symbols from LIBOBJS to the file
5601 -- Variable: extract_expsyms_cmds
5602 Commands to extract the exported symbols list from a shared
5603 library. These commands are executed if there is no file
5604 $OBJDIR/$SONAME-DEF, and should write the names of the exported
5605 symbols to that file, for the use of
5606 `old_archive_from_expsyms_cmds'.
5608 -- Variable: fast_install
5609 Determines whether libtool will privilege the installer or the
5610 developer. The assumption is that installers will seldom run
5611 programs in the build tree, and the developer will seldom install.
5612 This is only meaningful on platforms where
5613 SHLIBPATH_OVERRIDES_RUNPATH is not `yes', so FAST_INSTALL will be
5614 set to `needless' in this case. If FAST_INSTALL set to `yes',
5615 libtool will create programs that search for installed libraries,
5616 and, if a program is run in the build tree, a new copy will be
5617 linked on-demand to use the yet-to-be-installed libraries. If set
5618 to `no', libtool will create programs that use the
5619 yet-to-be-installed libraries, and will link a new copy of the
5620 program at install time. The default value is `yes' or
5621 `needless', depending on platform and configuration flags, and it
5622 can be turned from `yes' to `no' with the configure flag
5623 `--disable-fast-install'.
5625 On some systems, the linker always hardcodes paths to dependent
5626 libraries into the output. In this case, FAST_INSTALL is never
5627 set to `yes', and relinking at install time is triggered. This
5628 also means that DESTDIR installation does not work as expected.
5630 -- Variable: finish_cmds
5631 Commands to tell the dynamic linker how to find shared libraries
5632 in a specific directory.
5634 -- Variable: finish_eval
5635 Same as FINISH_CMDS, except the commands are not displayed.
5637 -- Variable: fix_srcfile_path
5638 Expression to fix the shell variable `$srcfile' for the compiler.
5640 -- Variable: global_symbol_pipe
5641 A pipeline that takes the output of NM, and produces a listing of
5642 raw symbols followed by their C names. For example:
5644 $ eval "$NM progname | $global_symbol_pipe"
5651 The first column contains the symbol type (used to tell data from
5652 code) but its meaning is system dependent.
5654 -- Variable: global_symbol_to_cdecl
5655 A pipeline that translates the output of GLOBAL_SYMBOL_PIPE into
5656 proper C declarations. Since some platforms, such as HP/UX, have
5657 linkers that differentiate code from data, data symbols are
5658 declared as data, and code symbols are declared as functions.
5660 -- Variable: hardcode_action
5661 Either `immediate' or `relink', depending on whether shared
5662 library paths can be hardcoded into executables before they are
5663 installed, or if they need to be relinked.
5665 -- Variable: hardcode_direct
5666 Set to `yes' or `no', depending on whether the linker hardcodes
5667 directories if a library is directly specified on the command line
5668 (such as `DIR/libNAME.a') when HARDCODE_LIBDIR_FLAG_SPEC is
5671 -- Variable: hardcode_direct_absolute
5672 Some architectures hardcode "absolute" library directories that
5673 can not be overridden by SHLIBPATH_VAR when HARDCODE_DIRECT is
5674 `yes'. In that case set HARDCODE_DIRECT_ABSOLUTE to `yes', or
5677 -- Variable: hardcode_into_libs
5678 Whether the platform supports hardcoding of run-paths into
5679 libraries. If enabled, linking of programs will be much simpler
5680 but libraries will need to be relinked during installation. Set
5683 -- Variable: hardcode_libdir_flag_spec
5684 Flag to hardcode a LIBDIR variable into a binary, so that the
5685 dynamic linker searches LIBDIR for shared libraries at runtime.
5686 If it is empty, libtool will try to use some other hardcoding
5689 -- Variable: hardcode_libdir_separator
5690 If the compiler only accepts a single HARDCODE_LIBDIR_FLAG, then
5691 this variable contains the string that should separate multiple
5692 arguments to that flag.
5694 -- Variable: hardcode_minus_L
5695 Set to `yes' or `no', depending on whether the linker hardcodes
5696 directories specified by `-L' flags into the resulting executable
5697 when HARDCODE_LIBDIR_FLAG_SPEC is specified.
5699 -- Variable: hardcode_shlibpath_var
5700 Set to `yes' or `no', depending on whether the linker hardcodes
5701 directories by writing the contents of `$shlibpath_var' into the
5702 resulting executable when HARDCODE_LIBDIR_FLAG_SPEC is specified.
5703 Set to `unsupported' if directories specified by `$shlibpath_var'
5704 are searched at run time, but not at link time.
5707 -- Variable: host_alias
5708 -- Variable: host_os
5709 Set to the specified and canonical names of the system that
5710 libtool was configured for.
5712 -- Variable: include_expsyms
5713 List of symbols that must always be exported when using
5716 -- Variable: inherit_rpath
5717 Whether the linker adds runtime paths of dependency libraries to
5718 the runtime path list, requiring libtool to relink the output when
5719 installing. Set to `yes' or `no'. Default is `no'.
5721 -- Variable: install_override_mode
5722 Permission mode override for installation of shared libraries. If
5723 the runtime linker fails to load libraries with wrong permissions,
5724 then it may fail to execute programs that are needed during
5725 installation, because these need the library that has just been
5726 installed. In this case, it is necessary to pass the mode to
5727 `install' with `-m INSTALL_OVERRIDE_MODE'.
5730 The standard old archive suffix (normally `a').
5732 -- Variable: libname_spec
5733 The format of a library name prefix. On all Unix systems, static
5734 libraries are called `libNAME.a', but on some systems (such as
5735 OS/2 or MS-DOS), the library is just called `NAME.a'.
5737 -- Variable: library_names_spec
5738 A list of shared library names. The first is the name of the file,
5739 the rest are symbolic links to the file. The name in the list is
5740 the file name that the linker finds when given `-lNAME'.
5742 -- Variable: link_all_deplibs
5743 Whether libtool must link a program against all its dependency
5744 libraries. Set to `yes' or `no'. Default is `unknown', which is
5745 a synonym for `yes'.
5747 -- Variable: link_static_flag
5748 Linker flag (passed through the C compiler) used to prevent dynamic
5751 -- Variable: macro_version
5752 -- Variable: macro_revision
5753 The release and revision from which the libtool.m4 macros were
5754 taken. This is used to ensure that macros and `ltmain.sh'
5755 correspond to the same Libtool version.
5757 -- Variable: max_cmd_len
5758 The approximate longest command line that can be passed to `$SHELL'
5759 without being truncated, as computed by `LT_CMD_MAX_LEN'.
5761 -- Variable: need_lib_prefix
5762 Whether we can `dlopen' modules without a `lib' prefix. Set to
5763 `yes' or `no'. By default, it is `unknown', which means the same
5764 as `yes', but documents that we are not really sure about it.
5765 `no' means that it is possible to `dlopen' a module without the
5768 -- Variable: need_version
5769 Whether versioning is required for libraries, i.e. whether the
5770 dynamic linker requires a version suffix for all libraries. Set
5771 to `yes' or `no'. By default, it is `unknown', which means the
5772 same as `yes', but documents that we are not really sure about it.
5774 -- Variable: need_locks
5775 Whether files must be locked to prevent conflicts when compiling
5776 simultaneously. Set to `yes' or `no'.
5778 -- Variable: no_builtin_flag
5779 Compiler flag to disable builtin functions that conflict with
5780 declaring external global symbols as `char'.
5782 -- Variable: no_undefined_flag
5783 The flag that is used by `archive_cmds' in order to declare that
5784 there will be no unresolved symbols in the resulting shared
5785 library. Empty, if no such flag is required.
5788 The name of the directory that contains temporary libtool files.
5791 The standard object file suffix (normally `o').
5793 -- Variable: pic_flag
5794 Any additional compiler flags for building library object files.
5796 -- Variable: postinstall_cmds
5797 -- Variable: old_postinstall_cmds
5798 Commands run after installing a shared or static library,
5801 -- Variable: postuninstall_cmds
5802 -- Variable: old_postuninstall_cmds
5803 Commands run after uninstalling a shared or static library,
5806 -- Variable: reload_cmds
5807 -- Variable: reload_flag
5808 Commands to create a reloadable object.
5810 -- Variable: runpath_var
5811 The environment variable that tells the linker which directories to
5812 hardcode in the resulting executable.
5814 -- Variable: shlibpath_overrides_runpath
5815 Indicates whether it is possible to override the hard-coded library
5816 search path of a program with an environment variable. If this is
5817 set to no, libtool may have to create two copies of a program in
5818 the build tree, one to be installed and one to be run in the build
5819 tree only. When each of these copies is created depends on the
5820 value of `fast_install'. The default value is `unknown', which is
5823 -- Variable: shlibpath_var
5824 The environment variable that tells the dynamic linker where to
5825 find shared libraries.
5827 -- Variable: soname_spec
5828 The name coded into shared libraries, if different from the real
5831 -- Variable: striplib
5832 -- Variable: old_striplib
5833 Command to strip a shared (`striplib') or static (`old_striplib')
5834 library, respectively. If these variables are empty, the strip
5835 flag in the install mode will be ignored for libraries (*note
5838 -- Variable: sys_lib_dlsearch_path_spec
5839 Expression to get the run-time system library search path.
5840 Directories that appear in this list are never hard-coded into
5843 -- Variable: sys_lib_search_path_spec
5844 Expression to get the compile-time system library search path.
5845 This variable is used by libtool when it has to test whether a
5846 certain library is shared or static. The directories listed in
5847 SHLIBPATH_VAR are automatically appended to this list, every time
5848 libtool runs (i.e., not at configuration time), because some
5849 linkers use this variable to extend the library search path.
5850 Linker switches such as `-L' also augment the search path.
5852 -- Variable: thread_safe_flag_spec
5853 Linker flag (passed through the C compiler) used to generate
5854 thread-safe libraries.
5856 -- Variable: version_type
5857 The library version numbering type. One of `libtool',
5858 `freebsd-aout', `freebsd-elf', `irix', `linux', `osf', `sunos',
5859 `windows', or `none'.
5861 -- Variable: whole_archive_flag_spec
5862 Compiler flag to generate shared objects from convenience archives.
5865 The C compiler flag that allows libtool to pass a flag directly to
5866 the linker. Used as: `${wl}SOME-FLAG'.
5868 Variables ending in `_cmds' or `_eval' contain a `~'-separated list
5869 of commands that are `eval'ed one after another. If any of the
5870 commands return a nonzero exit status, libtool generally exits with an
5873 Variables ending in `_spec' are `eval'ed before being used by
5877 File: libtool.info, Node: Cheap tricks, Prev: libtool script contents, Up: Maintaining
5882 Here are a few tricks that you can use in order to make maintainership
5885 * When people report bugs, ask them to use the `--config',
5886 `--debug', or `--features' flags, if you think they will help you.
5887 These flags are there to help you get information directly, rather
5888 than having to trust second-hand observation.
5890 * Rather than reconfiguring libtool every time I make a change to
5891 `ltmain.in', I keep a permanent `libtool' script in my PATH, which
5892 sources `ltmain.in' directly.
5894 The following steps describe how to create such a script, where
5895 `/home/src/libtool' is the directory containing the libtool source
5896 tree, `/home/src/libtool/libtool' is a libtool script that has been
5897 configured for your platform, and `~/bin' is a directory in your
5901 trick$ sed 's%^\(macro_version=\).*$%\1@VERSION@%;
5902 s%^\(macro_revision=\).*$%\1@package_revision@%;
5903 /^# ltmain\.sh/q' /home/src/libtool/libtool > libtool
5904 trick$ echo '. /home/src/libtool/ltmain.in' >> libtool
5905 trick$ chmod +x libtool
5906 trick$ libtool --version
5907 ltmain.sh (GNU @PACKAGE@@TIMESTAMP@) @VERSION@
5909 Copyright (C) 2009 Free Software Foundation, Inc.
5910 This is free software; see the source for copying conditions. There is NO
5911 warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
5914 The output of the final `libtool --version' command shows that the
5915 `ltmain.in' script is being used directly. Now, modify `~/bin/libtool'
5916 or `/home/src/libtool/ltmain.in' directly in order to test new changes
5917 without having to rerun `configure'.
5920 File: libtool.info, Node: GNU Free Documentation License, Next: Index, Prev: Maintaining, Up: Top
5922 Appendix A GNU Free Documentation License
5923 *****************************************
5925 Version 1.3, 3 November 2008
5927 Copyright (C) 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc.
5930 Everyone is permitted to copy and distribute verbatim copies
5931 of this license document, but changing it is not allowed.
5935 The purpose of this License is to make a manual, textbook, or other
5936 functional and useful document "free" in the sense of freedom: to
5937 assure everyone the effective freedom to copy and redistribute it,
5938 with or without modifying it, either commercially or
5939 noncommercially. Secondarily, this License preserves for the
5940 author and publisher a way to get credit for their work, while not
5941 being considered responsible for modifications made by others.
5943 This License is a kind of "copyleft", which means that derivative
5944 works of the document must themselves be free in the same sense.
5945 It complements the GNU General Public License, which is a copyleft
5946 license designed for free software.
5948 We have designed this License in order to use it for manuals for
5949 free software, because free software needs free documentation: a
5950 free program should come with manuals providing the same freedoms
5951 that the software does. But this License is not limited to
5952 software manuals; it can be used for any textual work, regardless
5953 of subject matter or whether it is published as a printed book.
5954 We recommend this License principally for works whose purpose is
5955 instruction or reference.
5957 1. APPLICABILITY AND DEFINITIONS
5959 This License applies to any manual or other work, in any medium,
5960 that contains a notice placed by the copyright holder saying it
5961 can be distributed under the terms of this License. Such a notice
5962 grants a world-wide, royalty-free license, unlimited in duration,
5963 to use that work under the conditions stated herein. The
5964 "Document", below, refers to any such manual or work. Any member
5965 of the public is a licensee, and is addressed as "you". You
5966 accept the license if you copy, modify or distribute the work in a
5967 way requiring permission under copyright law.
5969 A "Modified Version" of the Document means any work containing the
5970 Document or a portion of it, either copied verbatim, or with
5971 modifications and/or translated into another language.
5973 A "Secondary Section" is a named appendix or a front-matter section
5974 of the Document that deals exclusively with the relationship of the
5975 publishers or authors of the Document to the Document's overall
5976 subject (or to related matters) and contains nothing that could
5977 fall directly within that overall subject. (Thus, if the Document
5978 is in part a textbook of mathematics, a Secondary Section may not
5979 explain any mathematics.) The relationship could be a matter of
5980 historical connection with the subject or with related matters, or
5981 of legal, commercial, philosophical, ethical or political position
5984 The "Invariant Sections" are certain Secondary Sections whose
5985 titles are designated, as being those of Invariant Sections, in
5986 the notice that says that the Document is released under this
5987 License. If a section does not fit the above definition of
5988 Secondary then it is not allowed to be designated as Invariant.
5989 The Document may contain zero Invariant Sections. If the Document
5990 does not identify any Invariant Sections then there are none.
5992 The "Cover Texts" are certain short passages of text that are
5993 listed, as Front-Cover Texts or Back-Cover Texts, in the notice
5994 that says that the Document is released under this License. A
5995 Front-Cover Text may be at most 5 words, and a Back-Cover Text may
5996 be at most 25 words.
5998 A "Transparent" copy of the Document means a machine-readable copy,
5999 represented in a format whose specification is available to the
6000 general public, that is suitable for revising the document
6001 straightforwardly with generic text editors or (for images
6002 composed of pixels) generic paint programs or (for drawings) some
6003 widely available drawing editor, and that is suitable for input to
6004 text formatters or for automatic translation to a variety of
6005 formats suitable for input to text formatters. A copy made in an
6006 otherwise Transparent file format whose markup, or absence of
6007 markup, has been arranged to thwart or discourage subsequent
6008 modification by readers is not Transparent. An image format is
6009 not Transparent if used for any substantial amount of text. A
6010 copy that is not "Transparent" is called "Opaque".
6012 Examples of suitable formats for Transparent copies include plain
6013 ASCII without markup, Texinfo input format, LaTeX input format,
6014 SGML or XML using a publicly available DTD, and
6015 standard-conforming simple HTML, PostScript or PDF designed for
6016 human modification. Examples of transparent image formats include
6017 PNG, XCF and JPG. Opaque formats include proprietary formats that
6018 can be read and edited only by proprietary word processors, SGML or
6019 XML for which the DTD and/or processing tools are not generally
6020 available, and the machine-generated HTML, PostScript or PDF
6021 produced by some word processors for output purposes only.
6023 The "Title Page" means, for a printed book, the title page itself,
6024 plus such following pages as are needed to hold, legibly, the
6025 material this License requires to appear in the title page. For
6026 works in formats which do not have any title page as such, "Title
6027 Page" means the text near the most prominent appearance of the
6028 work's title, preceding the beginning of the body of the text.
6030 The "publisher" means any person or entity that distributes copies
6031 of the Document to the public.
6033 A section "Entitled XYZ" means a named subunit of the Document
6034 whose title either is precisely XYZ or contains XYZ in parentheses
6035 following text that translates XYZ in another language. (Here XYZ
6036 stands for a specific section name mentioned below, such as
6037 "Acknowledgements", "Dedications", "Endorsements", or "History".)
6038 To "Preserve the Title" of such a section when you modify the
6039 Document means that it remains a section "Entitled XYZ" according
6042 The Document may include Warranty Disclaimers next to the notice
6043 which states that this License applies to the Document. These
6044 Warranty Disclaimers are considered to be included by reference in
6045 this License, but only as regards disclaiming warranties: any other
6046 implication that these Warranty Disclaimers may have is void and
6047 has no effect on the meaning of this License.
6051 You may copy and distribute the Document in any medium, either
6052 commercially or noncommercially, provided that this License, the
6053 copyright notices, and the license notice saying this License
6054 applies to the Document are reproduced in all copies, and that you
6055 add no other conditions whatsoever to those of this License. You
6056 may not use technical measures to obstruct or control the reading
6057 or further copying of the copies you make or distribute. However,
6058 you may accept compensation in exchange for copies. If you
6059 distribute a large enough number of copies you must also follow
6060 the conditions in section 3.
6062 You may also lend copies, under the same conditions stated above,
6063 and you may publicly display copies.
6065 3. COPYING IN QUANTITY
6067 If you publish printed copies (or copies in media that commonly
6068 have printed covers) of the Document, numbering more than 100, and
6069 the Document's license notice requires Cover Texts, you must
6070 enclose the copies in covers that carry, clearly and legibly, all
6071 these Cover Texts: Front-Cover Texts on the front cover, and
6072 Back-Cover Texts on the back cover. Both covers must also clearly
6073 and legibly identify you as the publisher of these copies. The
6074 front cover must present the full title with all words of the
6075 title equally prominent and visible. You may add other material
6076 on the covers in addition. Copying with changes limited to the
6077 covers, as long as they preserve the title of the Document and
6078 satisfy these conditions, can be treated as verbatim copying in
6081 If the required texts for either cover are too voluminous to fit
6082 legibly, you should put the first ones listed (as many as fit
6083 reasonably) on the actual cover, and continue the rest onto
6086 If you publish or distribute Opaque copies of the Document
6087 numbering more than 100, you must either include a
6088 machine-readable Transparent copy along with each Opaque copy, or
6089 state in or with each Opaque copy a computer-network location from
6090 which the general network-using public has access to download
6091 using public-standard network protocols a complete Transparent
6092 copy of the Document, free of added material. If you use the
6093 latter option, you must take reasonably prudent steps, when you
6094 begin distribution of Opaque copies in quantity, to ensure that
6095 this Transparent copy will remain thus accessible at the stated
6096 location until at least one year after the last time you
6097 distribute an Opaque copy (directly or through your agents or
6098 retailers) of that edition to the public.
6100 It is requested, but not required, that you contact the authors of
6101 the Document well before redistributing any large number of
6102 copies, to give them a chance to provide you with an updated
6103 version of the Document.
6107 You may copy and distribute a Modified Version of the Document
6108 under the conditions of sections 2 and 3 above, provided that you
6109 release the Modified Version under precisely this License, with
6110 the Modified Version filling the role of the Document, thus
6111 licensing distribution and modification of the Modified Version to
6112 whoever possesses a copy of it. In addition, you must do these
6113 things in the Modified Version:
6115 A. Use in the Title Page (and on the covers, if any) a title
6116 distinct from that of the Document, and from those of
6117 previous versions (which should, if there were any, be listed
6118 in the History section of the Document). You may use the
6119 same title as a previous version if the original publisher of
6120 that version gives permission.
6122 B. List on the Title Page, as authors, one or more persons or
6123 entities responsible for authorship of the modifications in
6124 the Modified Version, together with at least five of the
6125 principal authors of the Document (all of its principal
6126 authors, if it has fewer than five), unless they release you
6127 from this requirement.
6129 C. State on the Title page the name of the publisher of the
6130 Modified Version, as the publisher.
6132 D. Preserve all the copyright notices of the Document.
6134 E. Add an appropriate copyright notice for your modifications
6135 adjacent to the other copyright notices.
6137 F. Include, immediately after the copyright notices, a license
6138 notice giving the public permission to use the Modified
6139 Version under the terms of this License, in the form shown in
6142 G. Preserve in that license notice the full lists of Invariant
6143 Sections and required Cover Texts given in the Document's
6146 H. Include an unaltered copy of this License.
6148 I. Preserve the section Entitled "History", Preserve its Title,
6149 and add to it an item stating at least the title, year, new
6150 authors, and publisher of the Modified Version as given on
6151 the Title Page. If there is no section Entitled "History" in
6152 the Document, create one stating the title, year, authors,
6153 and publisher of the Document as given on its Title Page,
6154 then add an item describing the Modified Version as stated in
6155 the previous sentence.
6157 J. Preserve the network location, if any, given in the Document
6158 for public access to a Transparent copy of the Document, and
6159 likewise the network locations given in the Document for
6160 previous versions it was based on. These may be placed in
6161 the "History" section. You may omit a network location for a
6162 work that was published at least four years before the
6163 Document itself, or if the original publisher of the version
6164 it refers to gives permission.
6166 K. For any section Entitled "Acknowledgements" or "Dedications",
6167 Preserve the Title of the section, and preserve in the
6168 section all the substance and tone of each of the contributor
6169 acknowledgements and/or dedications given therein.
6171 L. Preserve all the Invariant Sections of the Document,
6172 unaltered in their text and in their titles. Section numbers
6173 or the equivalent are not considered part of the section
6176 M. Delete any section Entitled "Endorsements". Such a section
6177 may not be included in the Modified Version.
6179 N. Do not retitle any existing section to be Entitled
6180 "Endorsements" or to conflict in title with any Invariant
6183 O. Preserve any Warranty Disclaimers.
6185 If the Modified Version includes new front-matter sections or
6186 appendices that qualify as Secondary Sections and contain no
6187 material copied from the Document, you may at your option
6188 designate some or all of these sections as invariant. To do this,
6189 add their titles to the list of Invariant Sections in the Modified
6190 Version's license notice. These titles must be distinct from any
6191 other section titles.
6193 You may add a section Entitled "Endorsements", provided it contains
6194 nothing but endorsements of your Modified Version by various
6195 parties--for example, statements of peer review or that the text
6196 has been approved by an organization as the authoritative
6197 definition of a standard.
6199 You may add a passage of up to five words as a Front-Cover Text,
6200 and a passage of up to 25 words as a Back-Cover Text, to the end
6201 of the list of Cover Texts in the Modified Version. Only one
6202 passage of Front-Cover Text and one of Back-Cover Text may be
6203 added by (or through arrangements made by) any one entity. If the
6204 Document already includes a cover text for the same cover,
6205 previously added by you or by arrangement made by the same entity
6206 you are acting on behalf of, you may not add another; but you may
6207 replace the old one, on explicit permission from the previous
6208 publisher that added the old one.
6210 The author(s) and publisher(s) of the Document do not by this
6211 License give permission to use their names for publicity for or to
6212 assert or imply endorsement of any Modified Version.
6214 5. COMBINING DOCUMENTS
6216 You may combine the Document with other documents released under
6217 this License, under the terms defined in section 4 above for
6218 modified versions, provided that you include in the combination
6219 all of the Invariant Sections of all of the original documents,
6220 unmodified, and list them all as Invariant Sections of your
6221 combined work in its license notice, and that you preserve all
6222 their Warranty Disclaimers.
6224 The combined work need only contain one copy of this License, and
6225 multiple identical Invariant Sections may be replaced with a single
6226 copy. If there are multiple Invariant Sections with the same name
6227 but different contents, make the title of each such section unique
6228 by adding at the end of it, in parentheses, the name of the
6229 original author or publisher of that section if known, or else a
6230 unique number. Make the same adjustment to the section titles in
6231 the list of Invariant Sections in the license notice of the
6234 In the combination, you must combine any sections Entitled
6235 "History" in the various original documents, forming one section
6236 Entitled "History"; likewise combine any sections Entitled
6237 "Acknowledgements", and any sections Entitled "Dedications". You
6238 must delete all sections Entitled "Endorsements."
6240 6. COLLECTIONS OF DOCUMENTS
6242 You may make a collection consisting of the Document and other
6243 documents released under this License, and replace the individual
6244 copies of this License in the various documents with a single copy
6245 that is included in the collection, provided that you follow the
6246 rules of this License for verbatim copying of each of the
6247 documents in all other respects.
6249 You may extract a single document from such a collection, and
6250 distribute it individually under this License, provided you insert
6251 a copy of this License into the extracted document, and follow
6252 this License in all other respects regarding verbatim copying of
6255 7. AGGREGATION WITH INDEPENDENT WORKS
6257 A compilation of the Document or its derivatives with other
6258 separate and independent documents or works, in or on a volume of
6259 a storage or distribution medium, is called an "aggregate" if the
6260 copyright resulting from the compilation is not used to limit the
6261 legal rights of the compilation's users beyond what the individual
6262 works permit. When the Document is included in an aggregate, this
6263 License does not apply to the other works in the aggregate which
6264 are not themselves derivative works of the Document.
6266 If the Cover Text requirement of section 3 is applicable to these
6267 copies of the Document, then if the Document is less than one half
6268 of the entire aggregate, the Document's Cover Texts may be placed
6269 on covers that bracket the Document within the aggregate, or the
6270 electronic equivalent of covers if the Document is in electronic
6271 form. Otherwise they must appear on printed covers that bracket
6272 the whole aggregate.
6276 Translation is considered a kind of modification, so you may
6277 distribute translations of the Document under the terms of section
6278 4. Replacing Invariant Sections with translations requires special
6279 permission from their copyright holders, but you may include
6280 translations of some or all Invariant Sections in addition to the
6281 original versions of these Invariant Sections. You may include a
6282 translation of this License, and all the license notices in the
6283 Document, and any Warranty Disclaimers, provided that you also
6284 include the original English version of this License and the
6285 original versions of those notices and disclaimers. In case of a
6286 disagreement between the translation and the original version of
6287 this License or a notice or disclaimer, the original version will
6290 If a section in the Document is Entitled "Acknowledgements",
6291 "Dedications", or "History", the requirement (section 4) to
6292 Preserve its Title (section 1) will typically require changing the
6297 You may not copy, modify, sublicense, or distribute the Document
6298 except as expressly provided under this License. Any attempt
6299 otherwise to copy, modify, sublicense, or distribute it is void,
6300 and will automatically terminate your rights under this License.
6302 However, if you cease all violation of this License, then your
6303 license from a particular copyright holder is reinstated (a)
6304 provisionally, unless and until the copyright holder explicitly
6305 and finally terminates your license, and (b) permanently, if the
6306 copyright holder fails to notify you of the violation by some
6307 reasonable means prior to 60 days after the cessation.
6309 Moreover, your license from a particular copyright holder is
6310 reinstated permanently if the copyright holder notifies you of the
6311 violation by some reasonable means, this is the first time you have
6312 received notice of violation of this License (for any work) from
6313 that copyright holder, and you cure the violation prior to 30 days
6314 after your receipt of the notice.
6316 Termination of your rights under this section does not terminate
6317 the licenses of parties who have received copies or rights from
6318 you under this License. If your rights have been terminated and
6319 not permanently reinstated, receipt of a copy of some or all of
6320 the same material does not give you any rights to use it.
6322 10. FUTURE REVISIONS OF THIS LICENSE
6324 The Free Software Foundation may publish new, revised versions of
6325 the GNU Free Documentation License from time to time. Such new
6326 versions will be similar in spirit to the present version, but may
6327 differ in detail to address new problems or concerns. See
6328 `http://www.gnu.org/copyleft/'.
6330 Each version of the License is given a distinguishing version
6331 number. If the Document specifies that a particular numbered
6332 version of this License "or any later version" applies to it, you
6333 have the option of following the terms and conditions either of
6334 that specified version or of any later version that has been
6335 published (not as a draft) by the Free Software Foundation. If
6336 the Document does not specify a version number of this License,
6337 you may choose any version ever published (not as a draft) by the
6338 Free Software Foundation. If the Document specifies that a proxy
6339 can decide which future versions of this License can be used, that
6340 proxy's public statement of acceptance of a version permanently
6341 authorizes you to choose that version for the Document.
6345 "Massive Multiauthor Collaboration Site" (or "MMC Site") means any
6346 World Wide Web server that publishes copyrightable works and also
6347 provides prominent facilities for anybody to edit those works. A
6348 public wiki that anybody can edit is an example of such a server.
6349 A "Massive Multiauthor Collaboration" (or "MMC") contained in the
6350 site means any set of copyrightable works thus published on the MMC
6353 "CC-BY-SA" means the Creative Commons Attribution-Share Alike 3.0
6354 license published by Creative Commons Corporation, a not-for-profit
6355 corporation with a principal place of business in San Francisco,
6356 California, as well as future copyleft versions of that license
6357 published by that same organization.
6359 "Incorporate" means to publish or republish a Document, in whole or
6360 in part, as part of another Document.
6362 An MMC is "eligible for relicensing" if it is licensed under this
6363 License, and if all works that were first published under this
6364 License somewhere other than this MMC, and subsequently
6365 incorporated in whole or in part into the MMC, (1) had no cover
6366 texts or invariant sections, and (2) were thus incorporated prior
6367 to November 1, 2008.
6369 The operator of an MMC Site may republish an MMC contained in the
6370 site under CC-BY-SA on the same site at any time before August 1,
6371 2009, provided the MMC is eligible for relicensing.
6374 ADDENDUM: How to use this License for your documents
6375 ====================================================
6377 To use this License in a document you have written, include a copy of
6378 the License in the document and put the following copyright and license
6379 notices just after the title page:
6381 Copyright (C) YEAR YOUR NAME.
6382 Permission is granted to copy, distribute and/or modify this document
6383 under the terms of the GNU Free Documentation License, Version 1.3
6384 or any later version published by the Free Software Foundation;
6385 with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
6386 Texts. A copy of the license is included in the section entitled ``GNU
6387 Free Documentation License''.
6389 If you have Invariant Sections, Front-Cover Texts and Back-Cover
6390 Texts, replace the "with...Texts." line with this:
6392 with the Invariant Sections being LIST THEIR TITLES, with
6393 the Front-Cover Texts being LIST, and with the Back-Cover Texts
6396 If you have Invariant Sections without Cover Texts, or some other
6397 combination of the three, merge those two alternatives to suit the
6400 If your document contains nontrivial examples of program code, we
6401 recommend releasing these examples in parallel under your choice of
6402 free software license, such as the GNU General Public License, to
6403 permit their use in free software.