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.4.2
18 Copyright (C) 1996-2011 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.
58 * Combined Index:: Full index.
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 about libtool
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 old 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.
179 * Cross compiling:: Issues that arise when cross compiling.
180 * File name conversion:: Converting file names between platforms.
181 * Windows DLLs:: Windows header defines.
185 * File Name Conversion Failure:: What happens when file name conversion fails
186 * Native MinGW File Name Conversion:: MSYS file name conversion idiosyncrasies
187 * Cygwin/Windows File Name Conversion:: Using `cygpath' to convert Cygwin file names
188 * Unix/Windows File Name Conversion:: Using Wine to convert Unix paths
189 * LT_CYGPATH:: Invoking `cygpath' from other environments
190 * Cygwin to MinGW Cross:: Other notes concerning MinGW cross
193 File: libtool.info, Node: Introduction, Next: Libtool paradigm, Prev: Top, Up: Top
198 In the past, if you were a source code package developer and wanted to
199 take advantage of the power of shared libraries, you needed to write
200 custom support code for each platform on which your package ran. You
201 also had to design a configuration interface so that the package
202 installer could choose what sort of libraries were built.
204 GNU Libtool simplifies your job by encapsulating both the
205 platform-specific dependencies, and the user interface, in a single
206 script. GNU Libtool is designed so that the complete functionality of
207 each host type is available via a generic interface, but nasty quirks
208 are hidden from the programmer.
210 GNU Libtool's consistent interface is reassuring... users don't need
211 to read obscure documentation in order to have their favorite source
212 package build shared libraries. They just run your package `configure'
213 script (or equivalent), and libtool does all the dirty work.
215 There are several examples throughout this document. All assume the
216 same environment: we want to build a library, `libhello', in a generic
219 `libhello' could be a shared library, a static library, or both...
220 whatever is available on the host system, as long as libtool has been
223 This chapter explains the original design philosophy of libtool.
224 Feel free to skip to the next chapter, unless you are interested in
225 history, or want to write code to extend libtool in a consistent way.
229 * Motivation:: Why does GNU need a libtool?
230 * Issues:: The problems that need to be addressed.
231 * Other implementations:: How other people have solved these issues.
232 * Postmortem:: Learning from past difficulties.
235 File: libtool.info, Node: Motivation, Next: Issues, Up: Introduction
237 1.1 Motivation for writing libtool
238 ==================================
240 Since early 1995, several different GNU developers have recognized the
241 importance of having shared library support for their packages. The
242 primary motivation for such a change is to encourage modularity and
243 reuse of code (both conceptually and physically) in GNU programs.
245 Such a demand means that the way libraries are built in GNU packages
246 needs to be general, to allow for any library type the package installer
247 might want. The problem is compounded by the absence of a standard
248 procedure for creating shared libraries on different platforms.
250 The following sections outline the major issues facing shared library
251 support in GNU, and how shared library support could be standardized
254 The following specifications were used in developing and evaluating
257 1. The system must be as elegant as possible.
259 2. The system must be fully integrated with the GNU Autoconf and
260 Automake utilities, so that it will be easy for GNU maintainers to
261 use. However, the system must not require these tools, so that it
262 can be used by non-GNU packages.
264 3. Portability to other (non-GNU) architectures and tools is
268 File: libtool.info, Node: Issues, Next: Other implementations, Prev: Motivation, Up: Introduction
270 1.2 Implementation issues
271 =========================
273 The following issues need to be addressed in any reusable shared library
274 system, specifically libtool:
276 1. The package installer should be able to control what sort of
279 2. It can be tricky to run dynamically linked programs whose
280 libraries have not yet been installed. `LD_LIBRARY_PATH' must be
281 set properly (if it is supported), or programs fail to run.
283 3. The system must operate consistently even on hosts that don't
284 support shared libraries.
286 4. The commands required to build shared libraries may differ wildly
287 from host to host. These need to be determined at configure time
290 5. It is not always obvious with what prefix or suffix a shared
291 library should be installed. This makes it difficult for
292 `Makefile' rules, since they generally assume that file names are
293 the same from host to host.
295 6. The system needs a simple library version number abstraction, so
296 that shared libraries can be upgraded in place. The programmer
297 should be informed how to design the interfaces to the library to
298 maximize binary compatibility.
300 7. The install `Makefile' target should warn the package installer to
301 set the proper environment variables (`LD_LIBRARY_PATH' or
302 equivalent), or run `ldconfig'.
305 File: libtool.info, Node: Other implementations, Next: Postmortem, Prev: Issues, Up: Introduction
307 1.3 Other implementations
308 =========================
310 Even before libtool was developed, many free software packages built and
311 installed their own shared libraries. At first, these packages were
312 examined to avoid reinventing existing features.
314 Now it is clear that none of these packages have documented the
315 details of shared library systems that libtool requires. So, other
316 packages have been more or less abandoned as influences.
319 File: libtool.info, Node: Postmortem, Prev: Other implementations, Up: Introduction
321 1.4 A postmortem analysis of other implementations
322 ==================================================
324 In all fairness, each of the implementations that were examined do the
325 job that they were intended to do, for a number of different host
326 systems. However, none of these solutions seem to function well as a
327 generalized, reusable component.
329 Most were too complex to use (much less modify) without understanding
330 exactly what the implementation does, and they were generally not
333 The main difficulty is that different vendors have different views of
334 what libraries are, and none of the packages that were examined seemed
335 to be confident enough to settle on a single paradigm that just _works_.
337 Ideally, libtool would be a standard that would be implemented as
338 series of extensions and modifications to existing library systems to
339 make them work consistently. However, it is not an easy task to
340 convince operating system developers to mend their evil ways, and
341 people want to build shared libraries right now, even on buggy, broken,
342 confused operating systems.
344 For this reason, libtool was designed as an independent shell script.
345 It isolates the problems and inconsistencies in library building that
346 plague `Makefile' writers by wrapping the compiler suite on different
347 platforms with a consistent, powerful interface.
349 With luck, libtool will be useful to and used by the GNU community,
350 and that the lessons that were learned in writing it will be taken up by
351 designers of future library systems.
354 File: libtool.info, Node: Libtool paradigm, Next: Using libtool, Prev: Introduction, Up: Top
356 2 The libtool paradigm
357 **********************
359 At first, libtool was designed to support an arbitrary number of library
360 object types. After libtool was ported to more platforms, a new
361 paradigm gradually developed for describing the relationship between
362 libraries and programs.
364 In summary, "libraries are programs with multiple entry points, and
365 more formally defined interfaces."
367 Version 0.7 of libtool was a complete redesign and rewrite of
368 libtool to reflect this new paradigm. So far, it has proved to be
369 successful: libtool is simpler and more useful than before.
371 The best way to introduce the libtool paradigm is to contrast it with
372 the paradigm of existing library systems, with examples from each. It
373 is a new way of thinking, so it may take a little time to absorb, but
374 when you understand it, the world becomes simpler.
377 File: libtool.info, Node: Using libtool, Next: Invoking libtool, Prev: Libtool paradigm, Up: Top
382 It makes little sense to talk about using libtool in your own packages
383 until you have seen how it makes your life simpler. The examples in
384 this chapter introduce the main features of libtool by comparing the
385 standard library building procedure to libtool's operation on two
389 An Ultrix 4.2 platform with only static libraries.
392 A NetBSD/i386 1.2 platform with shared libraries.
394 You can follow these examples on your own platform, using the
395 preconfigured libtool script that was installed with libtool (*note
398 Source files for the following examples are taken from the `demo'
399 subdirectory of the libtool distribution. Assume that we are building a
400 library, `libhello', out of the files `foo.c' and `hello.c'.
402 Note that the `foo.c' source file uses the `cos' math library
403 function, which is usually found in the standalone math library, and not
404 the C library (*note Trigonometric Functions: (libc)Trig Functions.).
405 So, we need to add `-lm' to the end of the link line whenever we link
406 `foo.lo' into an executable or a library (*note Inter-library
409 The same rule applies whenever you use functions that don't appear in
410 the standard C library... you need to add the appropriate `-lNAME' flag
411 to the end of the link line when you link against those objects.
413 After we have built that library, we want to create a program by
414 linking `main.o' against `libhello'.
418 * Creating object files:: Compiling object files for libraries.
419 * Linking libraries:: Creating libraries from object files.
420 * Linking executables:: Linking object files against libtool libraries.
421 * Debugging executables:: Running GDB on libtool-generated programs.
422 * Installing libraries:: Making libraries available to users.
423 * Installing executables:: Making programs available to users.
424 * Static libraries:: When shared libraries are not wanted.
427 File: libtool.info, Node: Creating object files, Next: Linking libraries, Up: Using libtool
429 3.1 Creating object files
430 =========================
432 To create an object file from a source file, the compiler is invoked
433 with the `-c' flag (and any other desired flags):
435 burger$ gcc -g -O -c main.c
438 The above compiler command produces an object file, usually named
439 `main.o', from the source file `main.c'.
441 For most library systems, creating object files that become part of a
442 static library is as simple as creating object files that are linked to
445 burger$ gcc -g -O -c foo.c
446 burger$ gcc -g -O -c hello.c
449 Shared libraries, however, may only be built from
450 "position-independent code" (PIC). So, special flags must be passed to
451 the compiler to tell it to generate PIC rather than the standard
452 position-dependent code.
454 Since this is a library implementation detail, libtool hides the
455 complexity of PIC compiler flags and uses separate library object files
456 (the PIC one lives in the `.libs' subdirectory and the static one lives
457 in the current directory). On systems without shared libraries, the
458 PIC library object files are not created, whereas on systems where all
459 code is PIC, such as AIX, the static ones are not created.
461 To create library object files for `foo.c' and `hello.c', simply
462 invoke libtool with the standard compilation command as arguments
463 (*note Compile mode::):
465 a23$ libtool --mode=compile gcc -g -O -c foo.c
466 gcc -g -O -c foo.c -o foo.o
467 a23$ libtool --mode=compile gcc -g -O -c hello.c
468 gcc -g -O -c hello.c -o hello.o
471 Note that libtool silently creates an additional control file on each
472 `compile' invocation. The `.lo' file is the libtool object, which
473 Libtool uses to determine what object file may be built into a shared
474 library. On `a23', only static libraries are supported so the library
475 objects look like this:
477 # foo.lo - a libtool object file
478 # Generated by ltmain.sh (GNU libtool) 2.4.2
480 # Please DO NOT delete this file!
481 # It is necessary for linking the library.
483 # Name of the PIC object.
486 # Name of the non-PIC object.
487 non_pic_object='foo.o'
489 On shared library systems, libtool automatically generates an
490 additional PIC object by inserting the appropriate PIC generation flags
491 into the compilation command:
493 burger$ libtool --mode=compile gcc -g -O -c foo.c
495 gcc -g -O -c foo.c -fPIC -DPIC -o .libs/foo.o
496 gcc -g -O -c foo.c -o foo.o >/dev/null 2>&1
499 Note that Libtool automatically created `.libs' directory upon its
500 first execution, where PIC library object files will be stored.
502 Since `burger' supports shared libraries, and requires PIC objects
503 to build them, Libtool has compiled a PIC object this time, and made a
504 note of it in the libtool object:
506 # foo.lo - a libtool object file
507 # Generated by ltmain.sh (GNU libtool) 2.4.2
509 # Please DO NOT delete this file!
510 # It is necessary for linking the library.
512 # Name of the PIC object.
513 pic_object='.libs/foo.o'
515 # Name of the non-PIC object.
516 non_pic_object='foo.o'
518 Notice that the second run of GCC has its output discarded. This is
519 done so that compiler warnings aren't annoyingly duplicated. If you
520 need to see both sets of warnings (you might have conditional code
521 inside `#ifdef PIC' for example), you can turn off suppression with the
522 `-no-suppress' option to libtool's compile mode:
524 burger$ libtool --mode=compile gcc -no-suppress -g -O -c hello.c
525 gcc -g -O -c hello.c -fPIC -DPIC -o .libs/hello.o
526 gcc -g -O -c hello.c -o hello.o
530 File: libtool.info, Node: Linking libraries, Next: Linking executables, Prev: Creating object files, Up: Using libtool
532 3.2 Linking libraries
533 =====================
535 Without libtool, the programmer would invoke the `ar' command to create
538 burger$ ar cru libhello.a hello.o foo.o
541 But of course, that would be too simple, so many systems require that
542 you run the `ranlib' command on the resulting library (to give it
543 better karma, or something):
545 burger$ ranlib libhello.a
548 It seems more natural to use the C compiler for this task, given
549 libtool's "libraries are programs" approach. So, on platforms without
550 shared libraries, libtool simply acts as a wrapper for the system `ar'
551 (and possibly `ranlib') commands.
553 Again, the libtool control file name (`.la' suffix) differs from the
554 standard library name (`.a' suffix). The arguments to libtool are the
555 same ones you would use to produce an executable named `libhello.la'
556 with your compiler (*note Link mode::):
558 a23$ libtool --mode=link gcc -g -O -o libhello.la foo.o hello.o
559 *** Warning: Linking the shared library libhello.la against the
560 *** non-libtool objects foo.o hello.o is not portable!
561 ar cru .libs/libhello.a
562 ranlib .libs/libhello.a
564 (cd .libs && rm -f libhello.la && ln -s ../libhello.la libhello.la)
567 Aha! Libtool caught a common error... trying to build a library
568 from standard objects instead of special `.lo' object files. This
569 doesn't matter so much for static libraries, but on shared library
570 systems, it is of great importance. (Note that you may replace
571 `libhello.la' with `libhello.a' in which case libtool won't issue the
572 warning any more. But although this method works, this is not intended
573 to be used because it makes you lose the benefits of using Libtool.)
575 So, let's try again, this time with the library object files.
576 Remember also that we need to add `-lm' to the link command line because
577 `foo.c' uses the `cos' math library function (*note Using libtool::).
579 Another complication in building shared libraries is that we need to
580 specify the path to the directory in which they (eventually) will be
581 installed (in this case, `/usr/local/lib')(1):
583 a23$ libtool --mode=link gcc -g -O -o libhello.la foo.lo hello.lo \
584 -rpath /usr/local/lib -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, let's try the same trick on the shared library platform:
593 burger$ libtool --mode=link gcc -g -O -o libhello.la foo.lo hello.lo \
594 -rpath /usr/local/lib -lm
595 rm -fr .libs/libhello.a .libs/libhello.la
596 ld -Bshareable -o .libs/libhello.so.0.0 .libs/foo.o .libs/hello.o -lm
597 ar cru .libs/libhello.a foo.o hello.o
598 ranlib .libs/libhello.a
600 (cd .libs && rm -f libhello.la && ln -s ../libhello.la libhello.la)
603 Now that's significantly cooler... Libtool just ran an obscure `ld'
604 command to create a shared library, as well as the static library.
606 Note how libtool creates extra files in the `.libs' subdirectory,
607 rather than the current directory. This feature is to make it easier
608 to clean up the build directory, and to help ensure that other programs
609 fail horribly if you accidentally forget to use libtool when you should.
611 Again, you may want to have a look at the `.la' file in order to see
612 what Libtool stores in it. In particular, you will see that Libtool
613 uses this file to remember the destination directory for the library
614 (the argument to `-rpath') as well as the dependency on the math
617 ---------- Footnotes ----------
619 (1) If you don't specify an `rpath', then libtool builds a libtool
620 convenience archive, not a shared library (*note Static libraries::).
623 File: libtool.info, Node: Linking executables, Next: Debugging executables, Prev: Linking libraries, Up: Using libtool
625 3.3 Linking executables
626 =======================
628 If you choose at this point to "install" the library (put it in a
629 permanent location) before linking executables against it, then you
630 don't need to use libtool to do the linking. Simply use the appropriate
631 `-L' and `-l' flags to specify the library's location.
633 Some system linkers insist on encoding the full directory name of
634 each shared library in the resulting executable. Libtool has to work
635 around this misfeature by special magic to ensure that only permanent
636 directory names are put into installed executables.
638 The importance of this bug must not be overlooked: it won't cause
639 programs to crash in obvious ways. It creates a security hole, and
640 possibly even worse, if you are modifying the library source code after
641 you have installed the package, you will change the behaviour of the
644 So, if you want to link programs against the library before you
645 install it, you must use libtool to do the linking.
647 Here's the old way of linking against an uninstalled library:
649 burger$ gcc -g -O -o hell.old main.o libhello.a -lm
652 Libtool's way is almost the same(1) (*note Link mode::):
654 a23$ libtool --mode=link gcc -g -O -o hell main.o libhello.la
655 gcc -g -O -o hell main.o ./.libs/libhello.a -lm
658 That looks too simple to be true. All libtool did was transform
659 `libhello.la' to `./.libs/libhello.a', but remember that `a23' has no
660 shared libraries. Notice that Libtool also remembered that
661 `libhello.la' depends on `-lm', so even though we didn't specify `-lm'
662 on the libtool command line(2) Libtool has added it to the `gcc' link
665 On `burger' Libtool links against the uninstalled shared library:
667 burger$ libtool --mode=link gcc -g -O -o hell main.o libhello.la
668 gcc -g -O -o .libs/hell main.o -L./.libs -R/usr/local/lib -lhello -lm
672 Now assume `libhello.la' had already been installed, and you want to
673 link a new program with it. You could figure out where it lives by
676 burger$ gcc -g -O -o test test.o -L/usr/local/lib -lhello -lm
678 However, unless `/usr/local/lib' is in the standard library search
679 path, you won't be able to run `test'. However, if you use libtool to
680 link the already-installed libtool library, it will do The Right Thing
683 burger$ libtool --mode=link gcc -g -O -o test test.o \
684 /usr/local/lib/libhello.la
685 gcc -g -O -o .libs/test test.o -Wl,--rpath \
686 -Wl,/usr/local/lib /usr/local/lib/libhello.a -lm
690 Note that libtool added the necessary run-time path flag, as well as
691 `-lm', the library libhello.la depended upon. Nice, huh?
693 Notice that the executable, `hell', was actually created in the
694 `.libs' subdirectory. Then, a wrapper script (or, on certain
695 platforms, a wrapper executable *note Wrapper executables::) was
696 created in the current directory.
698 Since libtool created a wrapper script, you should use libtool to
699 install it and debug it too. However, since the program does not depend
700 on any uninstalled libtool library, it is probably usable even without
703 On NetBSD 1.2, libtool encodes the installation directory of
704 `libhello', by using the `-R/usr/local/lib' compiler flag. Then, the
705 wrapper script guarantees that the executable finds the correct shared
706 library (the one in `./.libs') until it is properly installed.
708 Let's compare the two different programs:
710 burger$ time ./hell.old
712 ** This is not GNU Hello. There is no built-in mail reader. **
713 0.21 real 0.02 user 0.08 sys
716 ** This is not GNU Hello. There is no built-in mail reader. **
717 0.63 real 0.09 user 0.59 sys
720 The wrapper script takes significantly longer to execute, but at
721 least the results are correct, even though the shared library hasn't
724 So, what about all the space savings that shared libraries are
727 burger$ ls -l hell.old libhello.a
728 -rwxr-xr-x 1 gord gord 15481 Nov 14 12:11 hell.old
729 -rw-r--r-- 1 gord gord 4274 Nov 13 18:02 libhello.a
730 burger$ ls -l .libs/hell .libs/libhello.*
731 -rwxr-xr-x 1 gord gord 11647 Nov 14 12:10 .libs/hell
732 -rw-r--r-- 1 gord gord 4274 Nov 13 18:44 .libs/libhello.a
733 -rwxr-xr-x 1 gord gord 12205 Nov 13 18:44 .libs/libhello.so.0.0
736 Well, that sucks. Maybe I should just scrap this project and take up
739 Actually, it just proves an important point: shared libraries incur
740 overhead because of their (relative) complexity. In this situation, the
741 price of being dynamic is eight kilobytes, and the payoff is about four
742 kilobytes. So, having a shared `libhello' won't be an advantage until
743 we link it against at least a few more programs.
747 * Wrapper executables:: Wrapper executables for some platforms.
749 ---------- Footnotes ----------
751 (1) However, you should avoid using `-L' or `-l' flags to link
752 against an uninstalled libtool library. Just specify the relative path
753 to the `.la' file, such as `../intl/libintl.la'. This is a design
754 decision to eliminate any ambiguity when linking against uninstalled
757 (2) And why should we? `main.o' doesn't directly depend on `-lm'
761 File: libtool.info, Node: Wrapper executables, Up: Linking executables
763 3.3.1 Wrapper executables for uninstalled programs
764 --------------------------------------------------
766 Some platforms, notably those hosted on Windows such as Cygwin and
767 MinGW, use a wrapper executable rather than a wrapper script to ensure
768 proper operation of uninstalled programs linked by libtool against
769 uninstalled shared libraries. The wrapper executable thus performs the
770 same function as the wrapper script used on other platforms, but allows
771 to satisfy the `make' rules for the program, whose name ends in
772 `$(EXEEXT)'. The actual program executable is created below .libs, and
773 its name will end in `$(EXEEXT)' and may or may not contain an `lt-'
774 prefix. This wrapper executable sets various environment values so
775 that the program executable may locate its (uninstalled) shared
776 libraries, and then launches the program executable.
778 The wrapper executable provides a debug mode, enabled by passing the
779 command-line option `--lt-debug' (see below). When executing in debug
780 mode, diagnostic information will be printed to `stderr' before the
781 program executable is launched.
783 Finally, the wrapper executable supports a number of command line
784 options that may be useful when debugging the operation of the wrapper
785 system. All of these options begin with `--lt-', and if present they
786 and their arguments will be removed from the argument list passed on to
787 the program executable. Therefore, the program executable may not
788 employ command line options that begin with `--lt-'. (In fact, the
789 wrapper executable will detect any command line options that begin with
790 `--lt-' and abort with an error message if the option is not
791 recognized). If this presents a problem, please contact the Libtool
792 team at the Libtool bug reporting address <bug-libtool@gnu.org>.
794 These command line options include:
797 Causes the wrapper to print a copy of the wrapper _script_ to
801 Causes the wrapper to print diagnostic information to `stdout',
802 before launching the program executable.
805 For consistency, both the wrapper _script_ and the wrapper
806 _executable_ support these options.
809 File: libtool.info, Node: Debugging executables, Next: Installing libraries, Prev: Linking executables, Up: Using libtool
811 3.4 Debugging executables
812 =========================
814 If `hell' was a complicated program, you would certainly want to test
815 and debug it before installing it on your system. In the above
816 section, you saw how the libtool wrapper script makes it possible to run
817 the program directly, but unfortunately, this mechanism interferes with
821 GDB is free software and you are welcome to distribute copies of it
822 under certain conditions; type "show copying" to see the conditions.
823 There is no warranty for GDB; type "show warranty" for details.
824 GDB 4.16 (i386-unknown-netbsd), (C) 1996 Free Software Foundation, Inc.
826 "hell": not in executable format: File format not recognized
831 Sad. It doesn't work because GDB doesn't know where the executable
832 lives. So, let's try again, by invoking GDB directly on the executable:
834 burger$ gdb .libs/hell
835 GNU gdb 5.3 (i386-unknown-netbsd)
836 Copyright 2002 Free Software Foundation, Inc.
837 GDB is free software, covered by the GNU General Public License,
838 and you are welcome to change it and/or distribute copies of it
839 under certain conditions. Type "show copying" to see the conditions.
840 There is no warranty for GDB. Type "show warranty" for details.
842 Breakpoint 1 at 0x8048547: file main.c, line 29.
844 Starting program: /home/src/libtool/demo/.libs/hell
845 /home/src/libtool/demo/.libs/hell: can't load library 'libhello.so.0'
847 Program exited with code 020.
851 Argh. Now GDB complains because it cannot find the shared library
852 that `hell' is linked against. So, we must use libtool in order to
853 properly set the library path and run the debugger. Fortunately, we can
854 forget all about the `.libs' directory, and just run it on the
855 executable wrapper (*note Execute mode::):
857 burger$ libtool --mode=execute gdb hell
858 GNU gdb 5.3 (i386-unknown-netbsd)
859 Copyright 2002 Free Software Foundation, Inc.
860 GDB is free software, covered by the GNU General Public License,
861 and you are welcome to change it and/or distribute copies of it
862 under certain conditions. Type "show copying" to see the conditions.
863 There is no warranty for GDB. Type "show warranty" for details.
865 Breakpoint 1 at 0x8048547: file main.c, line 29.
867 Starting program: /home/src/libtool/demo/.libs/hell
869 Breakpoint 1, main (argc=1, argv=0xbffffc40) at main.c:29
870 29 printf ("Welcome to GNU Hell!\n");
872 The program is running. Quit anyway (and kill it)? (y or n) y
876 File: libtool.info, Node: Installing libraries, Next: Installing executables, Prev: Debugging executables, Up: Using libtool
878 3.5 Installing libraries
879 ========================
881 Installing libraries on a non-libtool system is quite
882 straightforward... just copy them into place:(1)
886 burger# cp libhello.a /usr/local/lib/libhello.a
889 Oops, don't forget the `ranlib' command:
891 burger# ranlib /usr/local/lib/libhello.a
894 Libtool installation is quite simple, as well. Just use the
895 `install' or `cp' command that you normally would (*note Install
898 a23# libtool --mode=install cp libhello.la /usr/local/lib/libhello.la
899 cp libhello.la /usr/local/lib/libhello.la
900 cp .libs/libhello.a /usr/local/lib/libhello.a
901 ranlib /usr/local/lib/libhello.a
904 Note that the libtool library `libhello.la' is also installed, to
905 help libtool with uninstallation (*note Uninstall mode::) and linking
906 (*note Linking executables::) and to help programs with dlopening
907 (*note Dlopened modules::).
909 Here is the shared library example:
911 burger# libtool --mode=install install -c libhello.la \
912 /usr/local/lib/libhello.la
913 install -c .libs/libhello.so.0.0 /usr/local/lib/libhello.so.0.0
914 install -c libhello.la /usr/local/lib/libhello.la
915 install -c .libs/libhello.a /usr/local/lib/libhello.a
916 ranlib /usr/local/lib/libhello.a
919 It is safe to specify the `-s' (strip symbols) flag if you use a
920 BSD-compatible install program when installing libraries. Libtool will
921 either ignore the `-s' flag, or will run a program that will strip only
922 debugging and compiler symbols from the library.
924 Once the libraries have been put in place, there may be some
925 additional configuration that you need to do before using them. First,
926 you must make sure that where the library is installed actually agrees
927 with the `-rpath' flag you used to build it.
929 Then, running `libtool -n finish LIBDIR' can give you further hints
930 on what to do (*note Finish mode::):
932 burger# libtool -n finish /usr/local/lib
933 PATH="$PATH:/sbin" ldconfig -m /usr/local/lib
934 -----------------------------------------------------------------
935 Libraries have been installed in:
938 To link against installed libraries in a given directory, LIBDIR,
939 you must use the `-LLIBDIR' flag during linking.
941 You will also need to do one of the following:
942 - add LIBDIR to the `LD_LIBRARY_PATH' environment variable
944 - add LIBDIR to the `LD_RUN_PATH' environment variable
946 - use the `-RLIBDIR' linker flag
948 See any operating system documentation about shared libraries for
949 more information, such as the ld and ld.so manual pages.
950 -----------------------------------------------------------------
953 After you have completed these steps, you can go on to begin using
954 the installed libraries. You may also install any executables that
955 depend on libraries you created.
957 ---------- Footnotes ----------
959 (1) Don't strip static libraries though, or they will be unusable.
962 File: libtool.info, Node: Installing executables, Next: Static libraries, Prev: Installing libraries, Up: Using libtool
964 3.6 Installing executables
965 ==========================
967 If you used libtool to link any executables against uninstalled libtool
968 libraries (*note Linking executables::), you need to use libtool to
969 install the executables after the libraries have been installed (*note
970 Installing libraries::).
972 So, for our Ultrix example, we would run:
974 a23# libtool --mode=install -c hell /usr/local/bin/hell
975 install -c hell /usr/local/bin/hell
978 On shared library systems that require wrapper scripts, libtool just
979 ignores the wrapper script and installs the correct binary:
981 burger# libtool --mode=install -c hell /usr/local/bin/hell
982 install -c .libs/hell /usr/local/bin/hell
986 File: libtool.info, Node: Static libraries, Prev: Installing executables, Up: Using libtool
988 3.7 Linking static libraries
989 ============================
991 Why return to `ar' and `ranlib' silliness when you've had a taste of
992 libtool? Well, sometimes it is desirable to create a static archive
993 that can never be shared. The most frequent case is when you have a
994 set of object files that you use to build several different libraries.
995 You can create a "convenience library" out of those objects, and link
996 against that with the other libraries, instead of listing all the
997 object files every time.
999 If you just want to link this convenience library into programs, then
1000 you could just ignore libtool entirely, and use the old `ar' and
1001 `ranlib' commands (or the corresponding GNU Automake `_LIBRARIES'
1002 rules). You can even install a convenience library using GNU Libtool,
1003 though you probably don't want to and hence GNU Automake doesn't allow
1006 burger$ libtool --mode=install ./install-sh -c libhello.a \
1007 /local/lib/libhello.a
1008 ./install-sh -c libhello.a /local/lib/libhello.a
1009 ranlib /local/lib/libhello.a
1012 Using libtool for static library installation protects your library
1013 from being accidentally stripped (if the installer used the `-s' flag),
1014 as well as automatically running the correct `ranlib' command.
1016 But libtool libraries are more than just collections of object files:
1017 they can also carry library dependency information, which old archives
1018 do not. If you want to create a libtool static convenience library, you
1019 can omit the `-rpath' flag and use `-static' to indicate that you're
1020 only interested in a static library. When you link a program with such
1021 a library, libtool will actually link all object files and dependency
1022 libraries into the program.
1024 If you omit both `-rpath' and `-static', libtool will create a
1025 convenience library that can be used to create other libtool libraries,
1026 even shared ones. Just like in the static case, the library behaves as
1027 an alias to a set of object files and dependency libraries, but in this
1028 case the object files are suitable for inclusion in shared libraries.
1029 But be careful not to link a single convenience library, directly or
1030 indirectly, into a single program or library, otherwise you may get
1031 errors about symbol redefinitions.
1033 The key is remembering that a convenience library contains PIC
1034 objects, and can be linked where a list of PIC objects makes sense;
1035 i.e. into a shared library. A static convenience library contains
1036 non-PIC objects, so can be linked into an old static library, or a
1039 When GNU Automake is used, you should use `noinst_LTLIBRARIES'
1040 instead of `lib_LTLIBRARIES' for convenience libraries, so that the
1041 `-rpath' option is not passed when they are linked.
1043 As a rule of thumb, link a libtool convenience library into at most
1044 one libtool library, and never into a program, and link libtool static
1045 convenience libraries only into programs, and only if you need to carry
1046 library dependency information to the user of the static convenience
1049 Another common situation where static linking is desirable is in
1050 creating a standalone binary. Use libtool to do the linking and add the
1054 File: libtool.info, Node: Invoking libtool, Next: Integrating libtool, Prev: Using libtool, Up: Top
1056 4 Invoking `libtool'
1057 ********************
1059 The `libtool' program has the following synopsis:
1061 libtool [OPTION]... [MODE-ARG]...
1063 and accepts the following options:
1066 Display libtool configuration variables and exit.
1069 Dump a trace of shell script execution to standard output. This
1070 produces a lot of output, so you may wish to pipe it to `less' (or
1071 `more') or redirect to a file.
1075 Don't create, modify, or delete any files, just show what commands
1076 would be executed by libtool.
1079 Display basic configuration options. This provides a way for
1080 packages to determine whether shared or static libraries will be
1084 Same as `--mode=finish'.
1087 Display short help message.
1090 Display a help message and exit. If `--mode=MODE' is specified,
1091 then detailed help for MODE is displayed.
1094 Display help for the general options as well as detailed help for
1095 each operation mode, and exit.
1098 Use MODE as the operation mode. When using libtool from the
1099 command line, you can give just MODE (or a unique abbreviation of
1100 it) as the first argument as a shorthand for the full
1101 `--mode=MODE'. For example, the following are equivalent:
1103 $ libtool --mode=execute --dry-run gdb prog.exe
1104 $ libtool execute --dry-run gdb prog.exe
1105 $ libtool exe --dry-run gdb prog.exe
1106 $ libtool e --dry-run gdb prog.exe
1108 MODE must be set to one of the following:
1111 Compile a source file into a libtool object.
1114 Automatically set the library path so that another program
1115 can use uninstalled libtool-generated programs or libraries.
1118 Create a library or an executable.
1121 Install libraries or executables.
1124 Complete the installation of libtool libraries on the system.
1127 Delete installed libraries or executables.
1130 Delete uninstalled libraries or executables.
1133 Use configuration variables from tag TAG (*note Tags::).
1135 `--preserve-dup-deps'
1136 Do not remove duplicate dependencies in libraries. When building
1137 packages with static libraries, the libraries may depend
1138 circularly on each other (shared libs can too, but for those it
1139 doesn't matter), so there are situations, where -la -lb -la is
1140 required, and the second -la may not be stripped or the link will
1141 fail. In cases where these duplications are required, this option
1142 will preserve them, only stripping the libraries that libtool
1143 knows it can safely.
1147 Do not print out any progress or informational messages.
1151 Print out progress and informational messages (enabled by default),
1152 as well as additional messages not ordinary seen by default.
1156 Print out the progress and informational messages that are seen by
1157 default. This option has no effect on whether the additional
1158 messages seen in `--verbose' mode are shown.
1161 Do not print out any additional informational messages beyond
1162 those ordinarily seen by default. This option has no effect on
1163 whether the ordinary progress and informational messages enabled
1164 by `--no-quiet' are shown.
1166 Thus, there are now three different message levels (not counting
1167 `--debug'), depending on whether the normal messages and/or the
1168 additional verbose messages are displayed. Note that there is no
1169 mechanism to diplay verbose messages, without also displaying
1173 Normal messages are displayed, verbose messages are not
1174 displayed. In addition to being the default mode, it can be
1175 forcibly achieved by using both option `--no-verbose' and
1176 either option `--no-silent' or option `--no-quiet'.
1179 Neither normal messages nor verbose messages are displayed.
1180 This mode can be achieved using either option `--silent' or
1184 Both normal messages and verbose messages are displayed. This
1185 mode can be achieved using either option `-v' or option
1189 Print libtool version information and exit.
1191 The current `libtool' implementation is done with a shell script
1192 that needs to be invoked by the shell which `configure' chose for
1193 configuring `libtool' (*note The Autoconf Manual:
1194 (autoconf)config.status Invocation.). This shell is set in the
1195 she-bang (`#!') line of the `libtool' script. Using a different shell
1196 may cause undefined behavior.
1198 The MODE-ARGS are a variable number of arguments, depending on the
1199 selected operation mode. In general, each MODE-ARG is interpreted by
1200 programs libtool invokes, rather than libtool itself.
1204 * Compile mode:: Creating library object files.
1205 * Link mode:: Generating executables and libraries.
1206 * Execute mode:: Debugging libtool-generated programs.
1207 * Install mode:: Making libraries and executables public.
1208 * Finish mode:: Completing a library installation.
1209 * Uninstall mode:: Removing installed executables and libraries.
1210 * Clean mode:: Removing uninstalled executables and libraries.
1213 File: libtool.info, Node: Compile mode, Next: Link mode, Up: Invoking libtool
1218 For "compile" mode, MODE-ARGS is a compiler command to be used in
1219 creating a "standard" object file. These arguments should begin with
1220 the name of the C compiler, and contain the `-c' compiler flag so that
1221 only an object file is created.
1223 Libtool determines the name of the output file by removing the
1224 directory component from the source file name, then substituting the
1225 source code suffix (e.g. `.c' for C source code) with the library
1226 object suffix, `.lo'.
1228 If shared libraries are being built, any necessary PIC generation
1229 flags are substituted into the compilation command.
1231 The following components of MODE-ARGS are treated specially:
1234 Note that the `-o' option is now fully supported. It is emulated
1235 on the platforms that don't support it (by locking and moving the
1236 objects), so it is really easy to use libtool, just with minor
1237 modifications to your Makefiles. Typing for example
1238 libtool --mode=compile gcc -c foo/x.c -o foo/x.lo
1239 will do what you expect.
1241 Note, however, that, if the compiler does not support `-c' and
1242 `-o', it is impossible to compile `foo/x.c' without overwriting an
1243 existing `./x.o'. Therefore, if you do have a source file
1244 `./x.c', make sure you introduce dependencies in your `Makefile'
1245 to make sure `./x.o' (or `./x.lo') is re-created after any
1246 sub-directory's `x.lo':
1248 x.o x.lo: foo/x.lo bar/x.lo
1250 This will also ensure that make won't try to use a temporarily
1251 corrupted `x.o' to create a program or library. It may cause
1252 needless recompilation on platforms that support `-c' and `-o'
1253 together, but it's the only way to make it safe for those that
1257 If both PIC and non-PIC objects are being built, libtool will
1258 normally suppress the compiler output for the PIC object
1259 compilation to save showing very similar, if not identical
1260 duplicate output for each object. If the `-no-suppress' option is
1261 given in compile mode, libtool will show the compiler output for
1265 Libtool will try to build only PIC objects.
1268 Libtool will try to build only non-PIC objects.
1271 Even if Libtool was configured with `--enable-static', the object
1272 file Libtool builds will not be suitable for static linking.
1273 Libtool will signal an error if it was configured with
1274 `--disable-shared', or if the host does not support shared
1278 Even if libtool was configured with `--disable-static', the object
1279 file Libtool builds *will* be suitable for static linking.
1283 Pass a flag directly to the compiler. With `-Wc,', multiple flags
1284 may be separated by commas, whereas `-Xcompiler ' passes through
1288 File: libtool.info, Node: Link mode, Next: Execute mode, Prev: Compile mode, Up: Invoking libtool
1293 "Link" mode links together object files (including library objects) to
1294 form another library or to create an executable program.
1296 MODE-ARGS consist of a command using the C compiler to create an
1297 output file (with the `-o' flag) from several object files.
1299 The following components of MODE-ARGS are treated specially:
1302 If OUTPUT-FILE is a program, then do not link it against any
1303 shared libraries at all. If OUTPUT-FILE is a library, then only
1304 create a static library. In general, this flag cannot be used
1305 together with `disable-static' (*note LT_INIT::).
1308 Tries to avoid versioning (*note Versioning::) for libraries and
1309 modules, i.e. no version information is stored and no symbolic
1310 links are created. If the platform requires versioning, this
1311 option has no effect.
1314 Pass the absolute name of the directory for installing executable
1315 programs (*note Directory Variables: (standards)Directory
1316 Variables.). `libtool' may use this value to install shared
1317 libraries there on systems that do not provide for any library
1318 hardcoding and use the directory of a program and the `PATH'
1319 variable as library search path. This is typically used for DLLs
1320 on Windows or other systems using the PE (Portable Executable)
1321 format. On other systems, `-bindir' is ignored. The default
1322 value used is `LIBDIR/../bin' for libraries installed to `LIBDIR'.
1323 You should not use `-bindir' for modules.
1326 Same as `-dlpreopen FILE', if native dlopening is not supported on
1327 the host platform (*note Dlopened modules::) or if the program is
1328 linked with `-static', `-static-libtool-libs', or `-all-static'.
1329 Otherwise, no effect. If FILE is `self' Libtool will make sure
1330 that the program can `dlopen' itself, either by enabling
1331 `-export-dynamic' or by falling back to `-dlpreopen self'.
1334 Link FILE into the output program, and add its symbols to the list
1335 of preloaded symbols (*note Dlpreopening::). If FILE is `self',
1336 the symbols of the program itself will be added to preloaded
1337 symbol lists. If FILE is `force' Libtool will make sure that a
1338 preloaded symbol list is always _defined_, regardless of whether
1342 Allow symbols from OUTPUT-FILE to be resolved with `dlsym' (*note
1343 Dlopened modules::).
1345 `-export-symbols SYMFILE'
1346 Tells the linker to export only the symbols listed in SYMFILE.
1347 The symbol file should end in `.sym' and must contain the name of
1348 one symbol per line. This option has no effect on some platforms.
1349 By default all symbols are exported.
1351 `-export-symbols-regex REGEX'
1352 Same as `-export-symbols', except that only symbols matching the
1353 regular expression REGEX are exported. By default all symbols are
1357 Search LIBDIR for required libraries that have already been
1361 OUTPUT-FILE requires the installed library `libNAME'. This option
1362 is required even when OUTPUT-FILE is not an executable.
1365 Creates a library that can be dlopened (*note Dlopened modules::).
1366 This option doesn't work for programs. Module names don't need to
1367 be prefixed with `lib'. In order to prevent name clashes,
1368 however, `libNAME' and `NAME' must not be used at the same time in
1372 Disable fast-install mode for the executable OUTPUT-FILE. Useful
1373 if the program won't be necessarily installed.
1376 Link an executable OUTPUT-FILE that can't be installed and
1377 therefore doesn't need a wrapper script on systems that allow
1378 hardcoding of library paths. Useful if the program is only used
1379 in the build tree, e.g., for testing or generating other files.
1382 Declare that OUTPUT-FILE does not depend on any libraries other
1383 than the ones listed on the command line, i.e., after linking, it
1384 will not have unresolved symbols. Some platforms require all
1385 symbols in shared libraries to be resolved at library creation
1386 (*note Inter-library dependencies::), and using this parameter
1387 allows `libtool' to assume that this will not happen.
1390 Create OUTPUT-FILE from the specified objects and libraries.
1393 Use a list of object files found in FILE to specify objects.
1395 `-precious-files-regex REGEX'
1396 Prevents removal of files from the temporary output directory whose
1397 names match this regular expression. You might specify `\.bbg?$'
1398 to keep those files created with `gcc -ftest-coverage' for example.
1401 Specify that the library was generated by release RELEASE of your
1402 package, so that users can easily tell which versions are newer
1403 than others. Be warned that no two releases of your package will
1404 be binary compatible if you use this flag. If you want binary
1405 compatibility, use the `-version-info' flag instead (*note
1409 If OUTPUT-FILE is a library, it will eventually be installed in
1410 LIBDIR. If OUTPUT-FILE is a program, add LIBDIR to the run-time
1411 path of the program. On platforms that don't support hardcoding
1412 library paths into executables and only search PATH for shared
1413 libraries, such as when OUTPUT-FILE is a Windows (or other PE
1414 platform) DLL, the `.la' control file will be installed in LIBDIR,
1415 but see `-bindir' above for the eventual destination of the `.dll'
1416 or other library file itself.
1419 If OUTPUT-FILE is a program, add LIBDIR to its run-time path. If
1420 OUTPUT-FILE is a library, add `-RLIBDIR' to its DEPENDENCY_LIBS,
1421 so that, whenever the library is linked into a program, LIBDIR
1422 will be added to its run-time path.
1425 If OUTPUT-FILE is a program, then link it against any uninstalled
1426 shared libtool libraries (this is the default behavior). If
1427 OUTPUT-FILE is a library, then only create a shared library. In
1428 the later case, libtool will signal an error if it was configured
1429 with `--disable-shared', or if the host does not support shared
1433 If OUTPUT-FILE is a libtool library, replace the system's standard
1434 file name extension for shared libraries with SUFFIX (most systems
1435 use `.so' here). This option is helpful in certain cases where an
1436 application requires that shared libraries (typically modules)
1437 have an extension other than the default one. Please note you
1438 must supply the full file name extension including any leading dot.
1441 If OUTPUT-FILE is a program, then do not link it against any
1442 uninstalled shared libtool libraries. If OUTPUT-FILE is a
1443 library, then only create a static library.
1445 `-static-libtool-libs'
1446 If OUTPUT-FILE is a program, then do not link it against any
1447 shared libtool libraries. If OUTPUT-FILE is a library, then only
1448 create a static library.
1450 `-version-info CURRENT[:REVISION[:AGE]]'
1451 If OUTPUT-FILE is a libtool library, use interface version
1452 information CURRENT, REVISION, and AGE to build it (*note
1453 Versioning::). Do *not* use this flag to specify package release
1454 information, rather see the `-release' flag.
1456 `-version-number MAJOR[:MINOR[:REVISION]]'
1457 If OUTPUT-FILE is a libtool library, compute interface version
1458 information so that the resulting library uses the specified
1459 major, minor and revision numbers. This is designed to permit
1460 libtool to be used with existing projects where identical version
1461 numbers are already used across operating systems. New projects
1462 should use the `-version-info' flag instead.
1465 if OUTPUT-FILE is a libtool library, declare that it provides a
1466 weak LIBNAME interface. This is a hint to libtool that there is
1467 no need to append LIBNAME to the list of dependency libraries of
1468 OUTPUT-FILE, because linking against OUTPUT-FILE already supplies
1469 the same interface (*note Linking with dlopened modules::).
1473 Pass a linker-specific flag directly to the compiler. With `-Wc,',
1474 multiple flags may be separated by commas, whereas `-Xcompiler '
1475 passes through commas unchanged.
1479 Pass a linker-specific flag directly to the linker.
1482 Pass a link-specific flag to the compiler driver (`CC') during
1485 If the OUTPUT-FILE ends in `.la', then a libtool library is created,
1486 which must be built only from library objects (`.lo' files). The
1487 `-rpath' option is required. In the current implementation, libtool
1488 libraries may not depend on other uninstalled libtool libraries (*note
1489 Inter-library dependencies::).
1491 If the OUTPUT-FILE ends in `.a', then a standard library is created
1492 using `ar' and possibly `ranlib'.
1494 If OUTPUT-FILE ends in `.o' or `.lo', then a reloadable object file
1495 is created from the input files (generally using `ld -r'). This method
1496 is often called "partial linking".
1498 Otherwise, an executable program is created.
1501 File: libtool.info, Node: Execute mode, Next: Install mode, Prev: Link mode, Up: Invoking libtool
1506 For "execute" mode, the library path is automatically set, then a
1507 program is executed.
1509 The first of the MODE-ARGS is treated as a program name, with the
1510 rest as arguments to that program.
1512 The following components of MODE-ARGS are treated specially:
1515 Add the directory containing FILE to the library path.
1517 This mode sets the library path environment variable according to any
1520 If any of the ARGS are libtool executable wrappers, then they are
1521 translated into the name of their corresponding uninstalled binary, and
1522 any of their required library directories are added to the library path.
1525 File: libtool.info, Node: Install mode, Next: Finish mode, Prev: Execute mode, Up: Invoking libtool
1530 In "install" mode, libtool interprets most of the elements of MODE-ARGS
1531 as an installation command beginning with `cp', or a BSD-compatible
1534 The following components of MODE-ARGS are treated specially:
1536 `-inst-prefix-dir INST-PREFIX-DIR'
1537 When installing into a temporary staging area, rather than the
1538 final `prefix', this argument is used to reflect the temporary
1539 path, in much the same way `automake' uses `DESTDIR'. For
1540 instance, if `prefix' is `/usr/local', but INST-PREFIX-DIR is
1541 `/tmp', then the object will be installed under `/tmp/usr/local/'.
1542 If the installed object is a libtool library, then the internal
1543 fields of that library will reflect only `prefix', not
1546 # Directory that this library needs to be installed in:
1547 libdir='/usr/local/lib'
1551 # Directory that this library needs to be installed in:
1552 libdir='/tmp/usr/local/lib'
1554 `inst-prefix' is also used to insure that if the installed object
1555 must be relinked upon installation, that it is relinked against
1556 the libraries in INST-PREFIX-DIR/`prefix', not `prefix'.
1558 In truth, this option is not really intended for use when calling
1559 libtool directly; it is automatically used when `libtool
1560 --mode=install' calls `libtool --mode=relink'. Libtool does this
1561 by analyzing the destination path given in the original `libtool
1562 --mode=install' command and comparing it to the expected
1563 installation path established during `libtool --mode=link'.
1565 Thus, end-users need change nothing, and `automake'-style `make
1566 install DESTDIR=/tmp' will Just Work(tm) most of the time. For
1567 systems where fast installation can not be turned on, relinking
1568 may be needed. In this case, a `DESTDIR' install will fail.
1570 Currently it is not generally possible to install into a temporary
1571 staging area that contains needed third-party libraries which are
1572 not yet visible at their final location.
1574 The rest of the MODE-ARGS are interpreted as arguments to the `cp'
1575 or `install' command.
1577 The command is run, and any necessary unprivileged post-installation
1578 commands are also completed.
1581 File: libtool.info, Node: Finish mode, Next: Uninstall mode, Prev: Install mode, Up: Invoking libtool
1586 "Finish" mode has two functions. One is to help system administrators
1587 install libtool libraries so that they can be located and linked into
1588 user programs. To invoke this functionality, pass the name of a library
1589 directory as MODE-ARG. Running this command may require superuser
1590 privileges, and the `--dry-run' option may be useful.
1592 The second is to facilitate transferring libtool libraries to a
1593 native compilation environment after they were built in a
1594 cross-compilation environment. Cross-compilation environments may rely
1595 on recent libtool features, and running libtool in finish mode will
1596 make it easier to work with older versions of libtool. This task is
1597 performed whenever the MODE-ARG is a `.la' file.
1600 File: libtool.info, Node: Uninstall mode, Next: Clean mode, Prev: Finish mode, Up: Invoking libtool
1605 "Uninstall" mode deletes installed libraries, executables and objects.
1607 The first MODE-ARG is the name of the program to use to delete files
1608 (typically `/bin/rm').
1610 The remaining MODE-ARGS are either flags for the deletion program
1611 (beginning with a `-'), or the names of files to delete.
1614 File: libtool.info, Node: Clean mode, Prev: Uninstall mode, Up: Invoking libtool
1619 "Clean" mode deletes uninstalled libraries, executables, objects and
1620 libtool's temporary files associated with them.
1622 The first MODE-ARG is the name of the program to use to delete files
1623 (typically `/bin/rm').
1625 The remaining MODE-ARGS are either flags for the deletion program
1626 (beginning with a `-'), or the names of files to delete.
1629 File: libtool.info, Node: Integrating libtool, Next: Other languages, Prev: Invoking libtool, Up: Top
1631 5 Integrating libtool with your package
1632 ***************************************
1634 This chapter describes how to integrate libtool with your packages so
1635 that your users can install hassle-free shared libraries.
1637 There are several ways in which Libtool may be integrated in your
1638 package, described in the following sections. Typically, the Libtool
1639 macro files as well as `ltmain.sh' are copied into your package using
1640 `libtoolize' and `aclocal' after setting up the `configure.ac' and
1641 toplevel `Makefile.am', then `autoconf' adds the needed tests to the
1642 `configure' script. These individual steps are often automated with
1645 Here is a diagram showing how such a typical Libtool configuration
1646 works when preparing a package for distribution, assuming that `m4' has
1647 been chosen as location for additional Autoconf macros, and `build-aux'
1648 as location for auxiliary build tools (*note The Autoconf Manual:
1651 libtool.m4 -----. .--> aclocal.m4 -----.
1652 ltoptions.m4 ---+ .-> aclocal* -+ +--> autoconf*
1653 ltversion.m4 ---+--+ `--> [copy in m4/] --+ |
1654 ltsugar.m4 -----+ | ^ | \/
1655 lt~obsolete.m4 -+ +-> libtoolize* -----' | configure
1656 [ltdl.m4] ------+ | |
1657 `----------------------------------'
1659 ltmain.sh -----------> libtoolize* -> [copy in build-aux/]
1661 During configuration, the `libtool' script is generated either
1662 through `config.status' or `config.lt':
1664 .--> config.status* --.
1665 configure* --+ +--> libtool
1666 `--> [config.lt*] ----' ^
1668 ltmain.sh --------------------------------'
1670 At `make' run time, `libtool' is then invoked as needed as a wrapper
1671 around compilers, linkers, install and cleanup programs.
1673 There are alternatives choices to several parts of the setup; for
1674 example, the Libtool macro files can either be copied or symlinked into
1675 the package, or copied into `aclocal.m4'. As another example, an
1676 external, pre-configured `libtool' script may be used, by-passing most
1677 of the tests and package-specific setup for Libtool.
1681 * Autoconf macros:: Autoconf macros exported by libtool.
1682 * Makefile rules:: Writing `Makefile' rules for libtool.
1683 * Using Automake:: Automatically supporting libtool.
1684 * Configuring:: Configuring libtool for a host system.
1685 * Distributing:: What files to distribute with your package.
1686 * Static-only libraries:: Sometimes shared libraries are just a pain.
1689 File: libtool.info, Node: Autoconf macros, Next: Makefile rules, Up: Integrating libtool
1691 5.1 Autoconf macros exported by libtool
1692 =======================================
1694 Libtool uses a number of macros to interrogate the host system when it
1695 is being built, and you can use some of them yourself too. Although
1696 there are a great many other macros in the libtool installed m4 files,
1697 these do not form part of the published interface, and are subject to
1698 change between releases.
1700 Macros in the `LT_CMD_' namespace check for various shell commands:
1702 -- Macro: LT_CMD_MAX_LEN
1703 Finds the longest command line that can be safely passed to
1704 `$SHELL' without being truncated, and store in the shell variable
1705 `$max_cmd_len'. It is only an approximate value, but command
1706 lines of this length or shorter are guaranteed not to be truncated.
1708 Macros in the `LT_FUNC_' namespace check characteristics of library
1711 -- Macro: LT_FUNC_DLSYM_USCORE
1712 `AC_DEFINE' the preprocessor symbol `DLSYM_USCORE' if we have to
1713 add an underscore to symbol-names passed in to `dlsym'.
1715 Macros in the `LT_LIB_' namespace check characteristics of system
1719 Set `LIBM' to the math library or libraries required on this
1722 -- Macro: LT_LIB_DLLOAD
1723 This is the macro used by `libltdl' to determine which dlloaders
1724 to use on this machine, if any. Several shell variables are set
1725 (and `AC_SUBST'ed) depending on the dlload interfaces are
1726 available on this machine. `LT_DLLOADERS' contains a list of
1727 libtool libraries that can be used, and if necessary also sets
1728 `LIBADD_DLOPEN' if additional system libraries are required by the
1729 `dlopen' loader, and `LIBADD_SHL_LOAD' if additional system
1730 libraries are required by the `shl_load' loader, respectively.
1731 Finally some symbols are set in `config.h' depending on the
1732 loaders that are found to work: `HAVE_LIBDL', `HAVE_SHL_LOAD',
1733 `HAVE_DYLD', `HAVE_DLD'.
1735 Macros in the `LT_PATH_' namespace search the system for the full path
1736 to particular system commands:
1738 -- Macro: LT_PATH_LD
1739 Add a `--with-gnu-ld' option to `configure'. Try to find the path
1740 to the linker used by `$CC', and whether it is the GNU linker.
1741 The result is stored in the shell variable `$LD', which is
1744 -- Macro: LT_PATH_NM
1745 Try to find a BSD-compatible `nm' or a MS-compatible `dumpbin'
1746 command on this machine. The result is stored in the shell
1747 variable `$NM', which is `AC_SUBST'ed.
1749 Macros in the `LT_SYS_' namespace probe for system characteristics:
1751 -- Macro: LT_SYS_DLOPEN_SELF
1752 Tests whether a program can dlopen itself, and then also whether
1753 the same program can still dlopen itself when statically linked.
1754 Results are stored in the shell variables `$enable_dlopen_self' and
1755 `enable_dlopen_self_static' respectively.
1757 -- Macro: LT_SYS_DLOPEN_DEPLIBS
1758 Define the preprocessor symbol `LTDL_DLOPEN_DEPLIBS' if the OS
1759 needs help to load dependent libraries for `dlopen' (or
1762 -- Macro: LT_SYS_DLSEARCH_PATH
1763 Define the preprocessor symbol `LT_DLSEARCH_PATH' to the system
1764 default library search path.
1766 -- Macro: LT_SYS_MODULE_EXT
1767 Define the preprocessor symbol `LT_MODULE_EXT' to the extension
1768 used for runtime loadable modules. If you use libltdl to open
1769 modules, then you can simply use the libtool library extension,
1772 -- Macro: LT_SYS_MODULE_PATH
1773 Define the preprocessor symbol `LT_MODULE_PATH_VAR' to the name of
1774 the shell environment variable that determines the run-time module
1777 -- Macro: LT_SYS_SYMBOL_USCORE
1778 Set the shell variable `sys_symbol_underscore' to `no' unless the
1779 compiler prefixes global symbols with an underscore.
1782 File: libtool.info, Node: Makefile rules, Next: Using Automake, Prev: Autoconf macros, Up: Integrating libtool
1784 5.2 Writing `Makefile' rules for libtool
1785 ========================================
1787 Libtool is fully integrated with Automake (*note Introduction:
1788 (automake)Top.), starting with Automake version 1.2.
1790 If you want to use libtool in a regular `Makefile' (or
1791 `Makefile.in'), you are on your own. If you're not using Automake, and
1792 you don't know how to incorporate libtool into your package you need to
1793 do one of the following:
1795 1. Download the latest Automake distribution from your nearest GNU
1796 mirror, install it, and start using it.
1798 2. Learn how to write `Makefile' rules by hand. They're sometimes
1799 complex, but if you're clever enough to write rules for compiling
1800 your old libraries, then you should be able to figure out new
1801 rules for libtool libraries (hint: examine the `Makefile.in' in
1802 the `tests/demo' subdirectory of the libtool distribution... note
1803 especially that it was automatically generated from the
1804 `Makefile.am' by Automake).
1807 File: libtool.info, Node: Using Automake, Next: Configuring, Prev: Makefile rules, Up: Integrating libtool
1809 5.3 Using Automake with libtool
1810 ===============================
1812 Libtool library support is implemented under the `LTLIBRARIES' primary.
1814 Here are some samples from the Automake `Makefile.am' in the libtool
1815 distribution's `demo' subdirectory.
1817 First, to link a program against a libtool library, just use the
1818 `program_LDADD'(1) variable:
1820 bin_PROGRAMS = hell hell_static
1822 # Build hell from main.c and libhello.la
1823 hell_SOURCES = main.c
1824 hell_LDADD = libhello.la
1826 # Create a statically linked version of hell.
1827 hell_static_SOURCES = main.c
1828 hell_static_LDADD = libhello.la
1829 hell_static_LDFLAGS = -static
1831 You may use the `program_LDFLAGS' variable to stuff in any flags you
1832 want to pass to libtool while linking `program' (such as `-static' to
1833 avoid linking uninstalled shared libtool libraries).
1835 Building a libtool library is almost as trivial... note the use of
1836 `libhello_la_LDFLAGS' to pass the `-version-info' (*note Versioning::)
1839 # Build a libtool library, libhello.la for installation in libdir.
1840 lib_LTLIBRARIES = libhello.la
1841 libhello_la_SOURCES = hello.c foo.c
1842 libhello_la_LDFLAGS = -version-info 3:12:1
1844 The `-rpath' option is passed automatically by Automake (except for
1845 libraries listed as `noinst_LTLIBRARIES'), so you should not specify it.
1847 *Note Building a Shared Library: (automake)A Shared Library, for
1850 ---------- Footnotes ----------
1852 (1) Since GNU Automake 1.5, the flags `-dlopen' or `-dlpreopen'
1853 (*note Link mode::) can be employed with the `program_LDADD' variable.
1854 Unfortunately, older releases didn't accept these flags, so if you are
1855 stuck with an ancient Automake, we recommend quoting the flag itself,
1856 and setting `program_DEPENDENCIES' too:
1858 program_LDADD = "-dlopen" libfoo.la
1859 program_DEPENDENCIES = libfoo.la
1862 File: libtool.info, Node: Configuring, Next: Distributing, Prev: Using Automake, Up: Integrating libtool
1864 5.4 Configuring libtool
1865 =======================
1867 Libtool requires intimate knowledge of your compiler suite and operating
1868 system in order to be able to create shared libraries and link against
1869 them properly. When you install the libtool distribution, a
1870 system-specific libtool script is installed into your binary directory.
1872 However, when you distribute libtool with your own packages (*note
1873 Distributing::), you do not always know the compiler suite and
1874 operating system that are used to compile your package.
1876 For this reason, libtool must be "configured" before it can be used.
1877 This idea should be familiar to anybody who has used a GNU `configure'
1878 script. `configure' runs a number of tests for system features, then
1879 generates the `Makefile's (and possibly a `config.h' header file),
1880 after which you can run `make' and build the package.
1882 Libtool adds its own tests to your `configure' script in order to
1883 generate a libtool script for the installer's host machine.
1887 * LT_INIT:: Configuring `libtool' in `configure.ac'.
1888 * Configure notes:: Platform-specific notes for configuration.
1891 File: libtool.info, Node: LT_INIT, Next: Configure notes, Up: Configuring
1893 5.4.1 The `LT_INIT' macro
1894 -------------------------
1896 If you are using GNU Autoconf (or Automake), you should add a call to
1897 `LT_INIT' to your `configure.ac' file. This macro adds many new tests
1898 to the `configure' script so that the generated libtool script will
1899 understand the characteristics of the host. It's the most important of
1900 a number of macros defined by Libtool:
1902 -- Macro: LT_PREREQ (VERSION)
1903 Ensure that a recent enough version of Libtool is being used. If
1904 the version of Libtool used for `LT_INIT' is earlier than VERSION,
1905 print an error message to the standard error output and exit with
1906 failure (exit status is 63). For example:
1910 -- Macro: LT_INIT (OPTIONS)
1911 -- Macro: AC_PROG_LIBTOOL
1912 -- Macro: AM_PROG_LIBTOOL
1913 Add support for the `--enable-shared', `--disable-shared',
1914 `--enable-static', `--disable-static', `--with-pic', and
1915 `--without-pic' `configure' flags.(1) `AC_PROG_LIBTOOL' and
1916 `AM_PROG_LIBTOOL' are deprecated names for older versions of this
1917 macro; `autoupdate' will upgrade your `configure.ac' files.
1919 By default, this macro turns on shared libraries if they are
1920 available, and also enables static libraries if they don't
1921 conflict with the shared libraries. You can modify these defaults
1922 by passing either `disable-shared' or `disable-static' in the
1923 option list to `LT_INIT', or using `AC_DISABLE_SHARED' or
1924 `AC_DISABLE_STATIC'.
1926 # Turn off shared libraries during beta-testing, since they
1927 # make the build process take too long.
1928 LT_INIT([disable-shared])
1930 The user may specify modified forms of the configure flags
1931 `--enable-shared' and `--enable-static' to choose whether shared
1932 or static libraries are built based on the name of the package.
1933 For example, to have shared `bfd' and `gdb' libraries built, but
1934 not shared `libg++', you can run all three `configure' scripts as
1937 trick$ ./configure --enable-shared=bfd,gdb
1939 In general, specifying `--enable-shared=PKGS' is the same as
1940 configuring with `--enable-shared' every package named in the
1941 comma-separated PKGS list, and every other package with
1942 `--disable-shared'. The `--enable-static=PKGS' flag behaves
1943 similarly, but it uses `--enable-static' and `--disable-static'.
1944 The same applies to the `--enable-fast-install=PKGS' flag, which
1945 uses `--enable-fast-install' and `--disable-fast-install'.
1947 The package name `default' matches any packages that have not set
1948 their name in the `PACKAGE' environment variable.
1950 The `--with-pic' and `--without-pic' configure flags can be used
1951 to specify whether or not `libtool' uses PIC objects. By default,
1952 `libtool' uses PIC objects for shared libraries and non-PIC
1953 objects for static libraries. The `--with-pic' option also
1954 accepts a comma-separated list of package names. Specifying
1955 `--with-pic=PKGS' is the same as configuring every package in PKGS
1956 with `--with-pic' and every other package with the default
1957 configuration. The package name `default' is treated the same as
1958 for `--enable-shared' and `--enable-static'.
1960 This macro also sets the shell variable `LIBTOOL_DEPS', that you
1961 can use to automatically update the libtool script if it becomes
1962 out-of-date. In order to do that, add to your `configure.ac':
1965 AC_SUBST([LIBTOOL_DEPS])
1967 and, to `Makefile.in' or `Makefile.am':
1969 LIBTOOL_DEPS = @LIBTOOL_DEPS@
1970 libtool: $(LIBTOOL_DEPS)
1971 $(SHELL) ./config.status libtool
1973 If you are using GNU Automake, you can omit the assignment, as
1974 Automake will take care of it. You'll obviously have to create
1975 some dependency on `libtool'.
1977 Aside from `disable-static' and `disable-shared', there are other
1978 options that you can pass to `LT_INIT' to modify its behaviour.
1979 Here is a full list:
1982 Enable checking for dlopen support. This option should be
1983 used if the package makes use of the `-dlopen' and
1984 `-dlpreopen' libtool flags, otherwise libtool will assume
1985 that the system does not support dlopening.
1988 This option should be used if the package has been ported to
1989 build clean dlls on win32 platforms. Usually this means that
1990 any library data items are exported with
1991 `__declspec(dllexport)' and imported with
1992 `__declspec(dllimport)'. If this macro is not used, libtool
1993 will assume that the package libraries are not dll clean and
1994 will build only static libraries on win32 hosts.
1996 Provision must be made to pass `-no-undefined' to `libtool'
1997 in link mode from the package `Makefile'. Naturally, if you
1998 pass `-no-undefined', you must ensure that all the library
1999 symbols *really are* defined at link time!
2001 `disable-fast-install'
2002 Change the default behaviour for `LT_INIT' to disable
2003 optimization for fast installation. The user may still
2004 override this default, depending on platform support, by
2005 specifying `--enable-fast-install' to `configure'.
2008 Change the default behaviour for `LT_INIT' to enable shared
2009 libraries. This is the default on all systems where Libtool
2010 knows how to create shared libraries. The user may still
2011 override this default by specifying `--disable-shared' to
2015 Change the default behaviour for `LT_INIT' to disable shared
2016 libraries. The user may still override this default by
2017 specifying `--enable-shared' to `configure'.
2020 Change the default behaviour for `LT_INIT' to enable static
2021 libraries. This is the default on all systems where shared
2022 libraries have been disabled for some reason, and on most
2023 systems where shared libraries have been enabled. If shared
2024 libraries are enabled, the user may still override this
2025 default by specifying `--disable-static' to `configure'.
2028 Change the default behaviour for `LT_INIT' to disable static
2029 libraries. The user may still override this default by
2030 specifying `--enable-static' to `configure'.
2033 Change the default behaviour for `libtool' to try to use only
2034 PIC objects. The user may still override this default by
2035 specifying `--without-pic' to `configure'.
2038 Change the default behaviour of `libtool' to try to use only
2039 non-PIC objects. The user may still override this default by
2040 specifying `--with-pic' to `configure'.
2044 -- Macro: LT_LANG (LANGUAGE)
2045 Enable `libtool' support for the language given if it has not yet
2046 already been enabled. Languages accepted are "C++", "Fortran 77",
2047 "Java", "Go", and "Windows Resource".
2049 If Autoconf language support macros such as `AC_PROG_CXX' are used
2050 in your `configure.ac', Libtool language support will automatically
2053 Conversely using `LT_LANG' to enable language support for Libtool
2054 will automatically enable Autoconf language support as well.
2056 Both of the following examples are therefore valid ways of adding
2057 C++ language support to Libtool.
2066 -- Macro: AC_LIBTOOL_DLOPEN
2067 This macro is deprecated, the `dlopen' option to `LT_INIT' should
2070 -- Macro: AC_LIBTOOL_WIN32_DLL
2071 This macro is deprecated, the `win32-dll' option to `LT_INIT'
2072 should be used instead.
2074 -- Macro: AC_DISABLE_FAST_INSTALL
2075 This macro is deprecated, the `disable-fast-install' option to
2076 `LT_INIT' should be used instead.
2078 -- Macro: AC_DISABLE_SHARED
2079 -- Macro: AM_DISABLE_SHARED
2080 Change the default behaviour for `LT_INIT' to disable shared
2081 libraries. The user may still override this default by specifying
2082 `--enable-shared'. The option `disable-shared' to `LT_INIT' is a
2083 shorthand for this. `AM_DISABLE_SHARED' is a deprecated alias for
2084 `AC_DISABLE_SHARED'.
2086 -- Macro: AC_ENABLE_SHARED
2087 -- Macro: AM_ENABLE_SHARED
2088 Change the default behaviour for `LT_INIT' to enable shared
2089 libraries. This is the default on all systems where Libtool knows
2090 how to create shared libraries. The user may still override this
2091 default by specifying `--disable-shared'. The option `shared' to
2092 `LT_INIT' is a shorthand for this. `AM_ENABLE_SHARED' is a
2093 deprecated alias for `AC_ENABLE_SHARED'.
2095 -- Macro: AC_DISABLE_STATIC
2096 -- Macro: AM_DISABLE_STATIC
2097 Change the default behaviour for `LT_INIT' to disable static
2098 libraries. The user may still override this default by specifying
2099 `--enable-static'. The option `disable-static' to `LT_INIT' is a
2100 shorthand for this. `AM_DISABLE_STATIC' is a deprecated alias for
2101 `AC_DISABLE_STATIC'.
2103 -- Macro: AC_ENABLE_STATIC
2104 -- Macro: AM_ENABLE_STATIC
2105 Change the default behaviour for `LT_INIT' to enable static
2106 libraries. This is the default on all systems where shared
2107 libraries have been disabled for some reason, and on most systems
2108 where shared libraries have been enabled. If shared libraries are
2109 enabled, the user may still override this default by specifying
2110 `--disable-static'. The option `static' to `LT_INIT' is a
2111 shorthand for this. `AM_ENABLE_STATIC' is a deprecated alias for
2114 The tests in `LT_INIT' also recognize the following environment
2118 The C compiler that will be used by the generated `libtool'. If
2119 this is not set, `LT_INIT' will look for `gcc' or `cc'.
2122 Compiler flags used to generate standard object files. If this is
2123 not set, `LT_INIT' will not use any such flags. It affects only
2124 the way `LT_INIT' runs tests, not the produced `libtool'.
2126 -- Variable: CPPFLAGS
2127 C preprocessor flags. If this is not set, `LT_INIT' will not use
2128 any such flags. It affects only the way `LT_INIT' runs tests, not
2129 the produced `libtool'.
2132 The system linker to use (if the generated `libtool' requires one).
2133 If this is not set, `LT_INIT' will try to find out what is the
2134 linker used by `CC'.
2136 -- Variable: LDFLAGS
2137 The flags to be used by `libtool' when it links a program. If
2138 this is not set, `LT_INIT' will not use any such flags. It
2139 affects only the way `LT_INIT' runs tests, not the produced
2143 The libraries to be used by `LT_INIT' when it links a program. If
2144 this is not set, `LT_INIT' will not use any such flags. It
2145 affects only the way `LT_INIT' runs tests, not the produced
2149 Program to use rather than checking for `nm'.
2152 Program to use rather than checking for `ranlib'.
2155 A command that creates a link of a program, a soft-link if
2156 possible, a hard-link otherwise. `LT_INIT' will check for a
2157 suitable program if this variable is not set.
2159 -- Variable: DLLTOOL
2160 Program to use rather than checking for `dlltool'. Only meaningful
2161 for Cygwin/MS-Windows.
2163 -- Variable: OBJDUMP
2164 Program to use rather than checking for `objdump'. Only meaningful
2165 for Cygwin/MS-Windows.
2168 Program to use rather than checking for `as'. Only used on
2169 Cygwin/MS-Windows at the moment.
2171 -- Variable: MANIFEST_TOOL
2172 Program to use rather than checking for `mt', the Manifest Tool.
2173 Only used on Cygwin/MS-Windows at the moment.
2175 With 1.3 era libtool, if you wanted to know any details of what
2176 libtool had discovered about your architecture and environment, you had
2177 to run the script with `--config' and grep through the results. This
2178 idiom was supported up to and including 1.5.x era libtool, where it was
2179 possible to call the generated libtool script from `configure.ac' as
2180 soon as `LT_INIT' had completed. However, one of the features of
2181 libtool 1.4 was that the libtool configuration was migrated out of a
2182 separate `ltconfig' file, and added to the `LT_INIT' macro (nee
2183 `AC_PROG_LIBTOOL'), so the results of the configuration tests were
2184 available directly to code in `configure.ac', rendering the call out to
2185 the generated libtool script obsolete.
2187 Starting with libtool 2.0, the multipass generation of the libtool
2188 script has been consolidated into a single `config.status' pass, which
2189 happens after all the code in `configure.ac' has completed. The
2190 implication of this is that the libtool script does not exist during
2191 execution of code from `configure.ac', and so obviously it cannot be
2192 called for `--config' details anymore. If you are upgrading projects
2193 that used this idiom to libtool 2.0 or newer, you should replace those
2194 calls with direct references to the equivalent Autoconf shell variables
2195 that are set by the configure time tests before being passed to
2196 `config.status' for inclusion in the generated libtool script.
2199 By default, the configured `libtool' script is generated by the
2200 call to `AC_OUTPUT' command, and there is rarely any need to use
2201 `libtool' from `configure'. However, sometimes it is necessary to
2202 run configure time compile and link tests using `libtool'. You
2203 can add `LT_OUTPUT' to your `configure.ac' any time after
2204 `LT_INIT' and any `LT_LANG' calls; that done, `libtool' will be
2205 created by a specially generated `config.lt' file, and available
2206 for use in later tests.
2208 Also, when `LT_OUTPUT' is used, for backwards compatibility with
2209 Automake regeneration rules, `config.status' will call `config.lt'
2210 to regenerate `libtool', rather than generating the file itself.
2212 When you invoke the `libtoolize' program (*note Invoking
2213 libtoolize::), it will tell you where to find a definition of
2214 `LT_INIT'. If you use Automake, the `aclocal' program will
2215 automatically add `LT_INIT' support to your `configure' script when it
2216 sees the invocation of `LT_INIT' in `configure.ac'.
2218 Because of these changes, and the runtime version compatibility
2219 checks Libtool now executes, we now advise *against* including a copy of
2220 `libtool.m4' (and brethren) in `acinclude.m4'. Instead, you should set
2221 your project macro directory with `AC_CONFIG_MACRO_DIR'. When you
2222 `libtoolize' your project, a copy of the relevant macro definitions
2223 will be placed in your `AC_CONFIG_MACRO_DIR', where `aclocal' can
2224 reference them directly from `aclocal.m4'.
2226 ---------- Footnotes ----------
2228 (1) `LT_INIT' requires that you define the `Makefile' variable
2229 `top_builddir' in your `Makefile.in'. Automake does this
2230 automatically, but Autoconf users should set it to the relative path to
2231 the top of your build directory (`../..', for example).
2234 File: libtool.info, Node: Configure notes, Prev: LT_INIT, Up: Configuring
2236 5.4.2 Platform-specific configuration notes
2237 -------------------------------------------
2239 While Libtool tries to hide as many platform-specific features as
2240 possible, some have to be taken into account when configuring either
2241 the Libtool package or a libtoolized package.
2243 * You currently need GNU make to build the Libtool package itself.
2245 * On AIX there are two different styles of shared linking, one in
2246 which symbols are bound at link-time and one in which symbols are
2247 bound at runtime only, similar to ELF. In case of doubt use
2248 `LDFLAGS=-Wl,-brtl' for the latter style.
2250 * On AIX, native tools are to be preferred over binutils; especially
2251 for C++ code, if using the AIX Toolbox GCC 4.0 and binutils,
2252 configure with `AR=/usr/bin/ar LD=/usr/bin/ld NM='/usr/bin/nm -B''.
2254 * On AIX, the `/bin/sh' is very slow due to its inefficient handling
2255 of here-documents. A modern shell is preferable:
2256 CONFIG_SHELL=/bin/bash; export $CONFIG_SHELL
2257 $CONFIG_SHELL ./configure [...]
2259 * For C++ code with templates, it may be necessary to specify the
2260 way the compiler will generate the instantiations. For Portland
2261 pgCC version5, use `CXX='pgCC --one_instantiation_per_object'' and
2262 avoid parallel `make'.
2264 * On Darwin, for C++ code with templates you need two level shared
2265 libraries. Libtool builds these by default if
2266 `MACOSX_DEPLOYMENT_TARGET' is set to 10.3 or later at `configure'
2267 time. See `rdar://problem/4135857' for more information on this
2270 * The default shell on UNICOS 9, a ksh 88e variant, is too buggy to
2271 correctly execute the libtool script. Users are advised to
2272 install a modern shell such as GNU bash.
2274 * Some HP-UX `sed' programs are horribly broken, and cannot handle
2275 libtool's requirements, so users may report unusual problems.
2276 There is no workaround except to install a working `sed' (such as
2277 GNU sed) on these systems.
2279 * The vendor-distributed NCR MP-RAS `cc' programs emits copyright on
2280 standard error that confuse tests on size of `conftest.err'. The
2281 workaround is to specify `CC' when run configure with `CC='cc
2284 * Any earlier DG/UX system with ELF executables, such as R3.10 or
2285 R4.10, is also likely to work, but hasn't been explicitly tested.
2287 * On Reliant Unix libtool has only been tested with the Siemens
2288 C-compiler and an old version of `gcc' provided by Marco Walther.
2290 * `libtool.m4', `ltdl.m4' and the `configure.ac' files are marked to
2291 use autoconf-mode, which is distributed with GNU Emacs 21,
2292 Autoconf itself, and all recent releases of XEmacs.
2294 * When building on some GNU/Linux systems for multilib targets
2295 `libtool' sometimes guesses the wrong paths that the linker and
2296 dynamic linker search by default. If this occurs, you may override
2297 libtool's guesses at `configure' time by setting the `autoconf'
2298 cache variables `lt_cv_sys_lib_search_path_spec' and
2299 `lt_cv_sys_lib_dlsearch_path_spec' respectively to the correct
2304 File: libtool.info, Node: Distributing, Next: Static-only libraries, Prev: Configuring, Up: Integrating libtool
2306 5.5 Including libtool in your package
2307 =====================================
2309 In order to use libtool, you need to include the following files with
2313 Attempt to guess a canonical system name.
2316 Canonical system name validation subroutine script.
2319 BSD-compatible `install' replacement script.
2322 A generic script implementing basic libtool functionality.
2324 Note that the libtool script itself should _not_ be included with
2325 your package. *Note Configuring::.
2327 You should use the `libtoolize' program, rather than manually
2328 copying these files into your package.
2332 * Invoking libtoolize:: `libtoolize' command line options.
2333 * Autoconf and LTLIBOBJS:: Autoconf automates LTLIBOBJS generation.
2336 File: libtool.info, Node: Invoking libtoolize, Next: Autoconf and LTLIBOBJS, Up: Distributing
2338 5.5.1 Invoking `libtoolize'
2339 ---------------------------
2341 The `libtoolize' program provides a standard way to add libtool support
2342 to your package. In the future, it may implement better usage
2343 checking, or other features to make libtool even easier to use.
2345 The `libtoolize' program has the following synopsis:
2347 libtoolize [OPTION]...
2349 and accepts the following options:
2353 Copy files from the libtool data directory rather than creating
2357 Dump a trace of shell script execution to standard output. This
2358 produces a lot of output, so you may wish to pipe it to `less' (or
2359 `more') or redirect to a file.
2363 Don't run any commands that modify the file system, just print them
2368 Replace existing libtool files. By default, `libtoolize' won't
2369 overwrite existing files.
2372 Display a help message and exit.
2374 `--ltdl [TARGET-DIRECTORY-NAME]'
2375 Install libltdl in the TARGET-DIRECTORY-NAME subdirectory of your
2376 package. Normally, the directory is extracted from the argument
2377 to `LT_CONFIG_LTDL_DIR' in `configure.ac', though you can also
2378 specify a subdirectory name here if you are not using Autoconf for
2379 example. If `libtoolize' can't determine the target directory,
2380 `libltdl' is used as the default.
2383 Normally, Libtoolize tries to diagnose use of deprecated libtool
2384 macros and other stylistic issues. If you are deliberately using
2385 outdated calling conventions, this option prevents Libtoolize from
2386 explaining how to update your project's Libtool conventions.
2389 If passed in conjunction with `--ltdl', this option will cause the
2390 `libltdl' installed by `libtoolize' to be set up for use with a
2391 non-recursive `automake' build. To make use of it, you will need
2392 to add the following to the `Makefile.am' of the parent project:
2394 ## libltdl/Makefile.inc appends to the following variables
2395 ## so we set them here before including it:
2402 noinst_LTLIBRARIES =
2411 include libltdl/Makefile.inc
2416 Work silently. `libtoolize --quiet' is used by GNU Automake to
2417 add libtool files to your package if necessary.
2420 If passed in conjunction with `--ltdl', this option will cause the
2421 `libtoolize' installed `libltdl' to be set up for use with a
2422 recursive `automake' build. To make use of it, you will need to
2423 adjust the parent project's `configure.ac':
2425 AC_CONFIG_FILES([libltdl/Makefile])
2432 If passed in conjunction with `--ltdl', this option will cause the
2433 `libtoolize' installed `libltdl' to be set up for independent
2434 configuration and compilation as a self-contained subproject. To
2435 make use of it, you should arrange for your build to call
2436 `libltdl/configure', and then run `make' in the `libltdl'
2437 directory (or the subdirectory you put libltdl into). If your
2438 project uses Autoconf, you can use the supplied `LT_WITH_LTDL'
2439 macro, or else call `AC_CONFIG_SUBDIRS' directly.
2441 Previous releases of `libltdl' built exclusively in this mode, but
2442 now it is the default mode both for backwards compatibility and
2443 because, for example, it is suitable for use in projects that wish
2444 to use `libltdl', but not use the Autotools for their own build
2449 Work noisily! Give a blow by blow account of what `libtoolize' is
2453 Print `libtoolize' version information and exit.
2455 Sometimes it can be useful to pass options to `libtoolize' even
2456 though it is called by another program, such as `autoreconf'. A
2457 limited number of options are parsed from the environment variable
2458 `LIBTOOLIZE_OPTIONS': currently `--debug', `--no-warn', `--quiet' and
2459 `--verbose'. Multiple options passed in `LIBTOOLIZE_OPTIONS' must be
2460 separated with a space, comma or a colon.
2462 By default, a warning is issued for unknown options found in
2463 `LIBTOOLIZE_OPTIONS' unless the first such option is `--no-warn'.
2464 Where `libtoolize' has always quit on receipt of an unknown option at
2465 the command line, this and all previous releases of `libtoolize' will
2466 continue unabated whatever the content of `LIBTOOLIZE_OPTIONS' (modulo
2467 some possible warning messages).
2469 trick$ LIBTOOLIZE_OPTIONS=--no-warn,--quiet autoreconf --install
2471 If `libtoolize' detects an explicit call to `AC_CONFIG_MACRO_DIR'
2472 (*note The Autoconf Manual: (autoconf)Input.) in your `configure.ac',
2473 it will put the Libtool macros in the specified directory.
2475 In the future other Autotools will automatically check the contents
2476 of `AC_CONFIG_MACRO_DIR', but at the moment it is more portable to add
2477 the macro directory to `ACLOCAL_AMFLAGS' in `Makefile.am', which is
2478 where the tools currently look. If `libtoolize' doesn't see
2479 `AC_CONFIG_MACRO_DIR', it too will honour the first `-I' argument in
2480 `ACLOCAL_AMFLAGS' when choosing a directory to store libtool
2481 configuration macros in. It is perfectly sensible to use both
2482 `AC_CONFIG_MACRO_DIR' and `ACLOCAL_AMFLAGS', as long as they are kept
2485 ACLOCAL_AMFLAGS = -I m4
2487 When you bootstrap your project with `aclocal', then you will need
2488 to explicitly pass the same macro directory with `aclocal''s `-I' flag:
2490 trick$ aclocal -I m4
2492 If `libtoolize' detects an explicit call to `AC_CONFIG_AUX_DIR'
2493 (*note The Autoconf Manual: (autoconf)Input.) in your `configure.ac', it
2494 will put the other support files in the specified directory. Otherwise
2495 they too end up in the project root directory.
2497 Unless `--no-warn' is passed, `libtoolize' displays hints for adding
2498 libtool support to your package, as well.
2501 File: libtool.info, Node: Autoconf and LTLIBOBJS, Prev: Invoking libtoolize, Up: Distributing
2503 5.5.2 Autoconf and `LTLIBOBJS'
2504 ------------------------------
2506 People used to add code like the following to their `configure.ac':
2508 LTLIBOBJS=`echo "$LIBOBJS" | sed 's/\.[^.]* /.lo /g;s/\.[^.]*$/.lo/'`
2509 AC_SUBST([LTLIBOBJS])
2511 This is no longer required (since Autoconf 2.54), and doesn't take
2512 Automake's deansification support into account either, so doesn't work
2513 correctly even with ancient Autoconfs!
2515 Provided you are using a recent (2.54 or better) incarnation of
2516 Autoconf, the call to `AC_OUTPUT' takes care of setting `LTLIBOBJS' up
2517 correctly, so you can simply delete such snippets from your
2518 `configure.ac' if you had them.
2521 File: libtool.info, Node: Static-only libraries, Prev: Distributing, Up: Integrating libtool
2523 5.6 Static-only libraries
2524 =========================
2526 When you are developing a package, it is often worthwhile to configure
2527 your package with the `--disable-shared' flag, or to override the
2528 defaults for `LT_INIT' by using the `disable-shared' option (*note The
2529 `LT_INIT' macro: LT_INIT.). This prevents libtool from building shared
2530 libraries, which has several advantages:
2532 * compilation is twice as fast, which can speed up your development
2535 * debugging is easier because you don't need to deal with any
2536 complexities added by shared libraries, and
2538 * you can see how libtool behaves on static-only platforms.
2540 You may want to put a small note in your package `README' to let
2541 other developers know that `--disable-shared' can save them time. The
2542 following example note is taken from the GIMP(1) distribution `README':
2544 The GIMP uses GNU Libtool in order to build shared libraries on a
2545 variety of systems. While this is very nice for making usable
2546 binaries, it can be a pain when trying to debug a program. For that
2547 reason, compilation of shared libraries can be turned off by
2548 specifying the `--disable-shared' option to `configure'.
2550 ---------- Footnotes ----------
2552 (1) GNU Image Manipulation Program, for those who haven't taken the
2553 plunge. See `http://www.gimp.org/'.
2556 File: libtool.info, Node: Other languages, Next: Versioning, Prev: Integrating libtool, Up: Top
2558 6 Using libtool with other languages
2559 ************************************
2561 Libtool was first implemented in order to add support for writing shared
2562 libraries in the C language. However, over time, libtool is being
2563 integrated with other languages, so that programmers are free to reap
2564 the benefits of shared libraries in their favorite programming language.
2566 This chapter describes how libtool interacts with other languages,
2567 and what special considerations you need to make if you do not use C.
2571 * C++ libraries:: Writing libraries for C++
2575 File: libtool.info, Node: C++ libraries, Next: Tags, Up: Other languages
2577 6.1 Writing libraries for C++
2578 =============================
2580 Creating libraries of C++ code should be a fairly straightforward
2581 process, because its object files differ from C ones in only three ways:
2583 1. Because of name mangling, C++ libraries are only usable by the C++
2584 compiler that created them. This decision was made by the
2585 designers of C++ in order to protect users from conflicting
2586 implementations of features such as constructors, exception
2589 2. On some systems, the C++ compiler must take special actions for the
2590 dynamic linker to run dynamic (i.e., run-time) initializers. This
2591 means that we should not call `ld' directly to link such
2592 libraries, and we should use the C++ compiler instead.
2594 3. C++ compilers will link some Standard C++ library in by default,
2595 but libtool does not know which are these libraries, so it cannot
2596 even run the inter-library dependence analyzer to check how to
2597 link it in. Therefore, running `ld' to link a C++ program or
2598 library is deemed to fail.
2600 Because of these three issues, Libtool has been designed to always
2601 use the C++ compiler to compile and link C++ programs and libraries. In
2602 some instances the `main()' function of a program must also be compiled
2603 with the C++ compiler for static C++ objects to be properly initialized.
2606 File: libtool.info, Node: Tags, Prev: C++ libraries, Up: Other languages
2611 Libtool supports multiple languages through the use of tags.
2612 Technically a tag corresponds to a set of configuration variables
2613 associated with a language. These variables tell `libtool' how it
2614 should create objects and libraries for each language.
2616 Tags are defined at `configure'-time for each language activated in
2617 the package (see `LT_LANG' in *note LT_INIT::). Here is the
2618 correspondence between language names and tags names.
2620 Language name Tag name
2629 `libtool' tries to automatically infer which tag to use from the
2630 compiler command being used to compile or link. If it can't infer a
2631 tag, then it defaults to the configuration for the `C' language.
2633 The tag can also be specified using `libtool''s `--tag=TAG' option
2634 (*note Invoking libtool::). It is a good idea to do so in `Makefile'
2635 rules, because that will allow users to substitute the compiler without
2636 relying on `libtool' inference heuristics. When no tag is specified,
2637 `libtool' will default to `CC'; this tag always exists.
2639 Finally, the set of tags available in a particular project can be
2640 retrieved by tracing for the `LT_SUPPORTED_TAG' macro (*note Trace
2644 File: libtool.info, Node: Versioning, Next: Library tips, Prev: Other languages, Up: Top
2646 7 Library interface versions
2647 ****************************
2649 The most difficult issue introduced by shared libraries is that of
2650 creating and resolving runtime dependencies. Dependencies on programs
2651 and libraries are often described in terms of a single name, such as
2652 `sed'. So, one may say "libtool depends on sed," and that is good
2653 enough for most purposes.
2655 However, when an interface changes regularly, we need to be more
2656 specific: "Gnus 5.1 requires Emacs 19.28 or above." Here, the
2657 description of an interface consists of a name, and a "version number."
2659 Even that sort of description is not accurate enough for some
2660 purposes. What if Emacs 20 changes enough to break Gnus 5.1?
2662 The same problem exists in shared libraries: we require a formal
2663 version system to describe the sorts of dependencies that programs have
2664 on shared libraries, so that the dynamic linker can guarantee that
2665 programs are linked only against libraries that provide the interface
2670 * Interfaces:: What are library interfaces?
2671 * Libtool versioning:: Libtool's versioning system.
2672 * Updating version info:: Changing version information before releases.
2673 * Release numbers:: Breaking binary compatibility for aesthetics.
2676 File: libtool.info, Node: Interfaces, Next: Libtool versioning, Up: Versioning
2678 7.1 What are library interfaces?
2679 ================================
2681 Interfaces for libraries may be any of the following (and more):
2683 * global variables: both names and types
2685 * global functions: argument types and number, return types, and
2688 * standard input, standard output, standard error, and file formats
2690 * sockets, pipes, and other inter-process communication protocol
2693 Note that static functions do not count as interfaces, because they
2694 are not directly available to the user of the library.
2697 File: libtool.info, Node: Libtool versioning, Next: Updating version info, Prev: Interfaces, Up: Versioning
2699 7.2 Libtool's versioning system
2700 ===============================
2702 Libtool has its own formal versioning system. It is not as flexible as
2703 some, but it is definitely the simplest of the more powerful versioning
2706 Think of a library as exporting several sets of interfaces,
2707 arbitrarily represented by integers. When a program is linked against
2708 a library, it may use any subset of those interfaces.
2710 Libtool's description of the interfaces that a program uses is
2711 simple: it encodes the least and the greatest interface numbers in the
2712 resulting binary (FIRST-INTERFACE, LAST-INTERFACE).
2714 The dynamic linker is guaranteed that if a library supports _every_
2715 interface number between FIRST-INTERFACE and LAST-INTERFACE, then the
2716 program can be relinked against that library.
2718 Note that this can cause problems because libtool's compatibility
2719 requirements are actually stricter than is necessary.
2721 Say `libhello' supports interfaces 5, 16, 17, 18, and 19, and that
2722 libtool is used to link `test' against `libhello'.
2724 Libtool encodes the numbers 5 and 19 in `test', and the dynamic
2725 linker will only link `test' against libraries that support _every_
2726 interface between 5 and 19. So, the dynamic linker refuses to link
2727 `test' against `libhello'!
2729 In order to eliminate this problem, libtool only allows libraries to
2730 declare consecutive interface numbers. So, `libhello' can declare at
2731 most that it supports interfaces 16 through 19. Then, the dynamic
2732 linker will link `test' against `libhello'.
2734 So, libtool library versions are described by three integers:
2737 The most recent interface number that this library implements.
2740 The implementation number of the CURRENT interface.
2743 The difference between the newest and oldest interfaces that this
2744 library implements. In other words, the library implements all the
2745 interface numbers in the range from number `CURRENT - AGE' to
2748 If two libraries have identical CURRENT and AGE numbers, then the
2749 dynamic linker chooses the library with the greater REVISION number.
2752 File: libtool.info, Node: Updating version info, Next: Release numbers, Prev: Libtool versioning, Up: Versioning
2754 7.3 Updating library version information
2755 ========================================
2757 If you want to use libtool's versioning system, then you must specify
2758 the version information to libtool using the `-version-info' flag
2759 during link mode (*note Link mode::).
2761 This flag accepts an argument of the form
2762 `CURRENT[:REVISION[:AGE]]'. So, passing `-version-info 3:12:1' sets
2763 CURRENT to 3, REVISION to 12, and AGE to 1.
2765 If either REVISION or AGE are omitted, they default to 0. Also note
2766 that AGE must be less than or equal to the CURRENT interface number.
2768 Here are a set of rules to help you update your library version
2771 1. Start with version information of `0:0:0' for each libtool library.
2773 2. Update the version information only immediately before a public
2774 release of your software. More frequent updates are unnecessary,
2775 and only guarantee that the current interface number gets larger
2778 3. If the library source code has changed at all since the last
2779 update, then increment REVISION (`C:R:A' becomes `C:r+1:A').
2781 4. If any interfaces have been added, removed, or changed since the
2782 last update, increment CURRENT, and set REVISION to 0.
2784 5. If any interfaces have been added since the last public release,
2787 6. If any interfaces have been removed or changed since the last
2788 public release, then set AGE to 0.
2790 *_Never_* try to set the interface numbers so that they correspond
2791 to the release number of your package. This is an abuse that only
2792 fosters misunderstanding of the purpose of library versions. Instead,
2793 use the `-release' flag (*note Release numbers::), but be warned that
2794 every release of your package will not be binary compatible with any
2797 The following explanation may help to understand the above rules a
2798 bit better: consider that there are three possible kinds of reactions
2799 from users of your library to changes in a shared library:
2801 1. Programs using the previous version may use the new version as
2802 drop-in replacement, and programs using the new version can also
2803 work with the previous one. In other words, no recompiling nor
2804 relinking is needed. In this case, bump REVISION only, don't touch
2807 2. Programs using the previous version may use the new version as
2808 drop-in replacement, but programs using the new version may use
2809 APIs not present in the previous one. In other words, a program
2810 linking against the new version may fail with "unresolved symbols"
2811 if linking against the old version at runtime: set REVISION to 0,
2812 bump CURRENT and AGE.
2814 3. Programs may need to be changed, recompiled, relinked in order to
2815 use the new version. Bump CURRENT, set REVISION and AGE to 0.
2817 In the above description, _programs_ using the library in question may
2818 also be replaced by other libraries using it.
2821 File: libtool.info, Node: Release numbers, Prev: Updating version info, Up: Versioning
2823 7.4 Managing release information
2824 ================================
2826 Often, people want to encode the name of the package release into the
2827 shared library so that it is obvious to the user which package their
2828 programs are linked against. This convention is used especially on
2831 trick$ ls /usr/lib/libbfd*
2832 /usr/lib/libbfd.a /usr/lib/libbfd.so.2.7.0.2
2836 On `trick', `/usr/lib/libbfd.so' is a symbolic link to
2837 `libbfd.so.2.7.0.2', which was distributed as a part of
2840 Unfortunately, this convention conflicts directly with libtool's
2841 idea of library interface versions, because the library interface
2842 rarely changes at the same time that the release number does, and the
2843 library suffix is never the same across all platforms.
2845 So, in order to accommodate both views, you can use the `-release'
2846 flag in order to set release information for libraries for which you do
2847 not want to use `-version-info'. For the `libbfd' example, the next
2848 release that uses libtool should be built with `-release 2.9.0', which
2849 will produce the following files on GNU/Linux:
2851 trick$ ls /usr/lib/libbfd*
2852 /usr/lib/libbfd-2.9.0.so /usr/lib/libbfd.a
2856 In this case, `/usr/lib/libbfd.so' is a symbolic link to
2857 `libbfd-2.9.0.so'. This makes it obvious that the user is dealing with
2858 `binutils-2.9.0', without compromising libtool's idea of interface
2861 Note that this option causes a modification of the library name, so
2862 do not use it unless you want to break binary compatibility with any
2863 past library releases. In general, you should only use `-release' for
2864 package-internal libraries or for ones whose interfaces change very
2868 File: libtool.info, Node: Library tips, Next: Inter-library dependencies, Prev: Versioning, Up: Top
2870 8 Tips for interface design
2871 ***************************
2873 Writing a good library interface takes a lot of practice and thorough
2874 understanding of the problem that the library is intended to solve.
2876 If you design a good interface, it won't have to change often, you
2877 won't have to keep updating documentation, and users won't have to keep
2878 relearning how to use the library.
2880 Here is a brief list of tips for library interface design that may
2881 help you in your exploits:
2884 Try to make every interface truly minimal, so that you won't need
2885 to delete entry points very often.
2887 Avoid interface changes
2888 Some people love redesigning and changing entry points just for
2889 the heck of it (note: _renaming_ a function is considered changing
2890 an entry point). Don't be one of those people. If you must
2891 redesign an interface, then try to leave compatibility functions
2892 behind so that users don't need to rewrite their existing code.
2894 Use opaque data types
2895 The fewer data type definitions a library user has access to, the
2896 better. If possible, design your functions to accept a generic
2897 pointer (that you can cast to an internal data type), and provide
2898 access functions rather than allowing the library user to directly
2899 manipulate the data. That way, you have the freedom to change the
2900 data structures without changing the interface.
2902 This is essentially the same thing as using abstract data types and
2903 inheritance in an object-oriented system.
2906 If you are careful to document each of your library's global
2907 functions and variables in header files, and include them in your
2908 library source files, then the compiler will let you know if you
2909 make any interface changes by accident (*note C header files::).
2911 Use the `static' keyword (or equivalent) whenever possible
2912 The fewer global functions your library has, the more flexibility
2913 you'll have in changing them. Static functions and variables may
2914 change forms as often as you like... your users cannot access
2915 them, so they aren't interface changes.
2917 Be careful with array dimensions
2918 The number of elements in a global array is part of an interface,
2919 even if the header just declares `extern int foo[];'. This is
2920 because on i386 and some other SVR4/ELF systems, when an
2921 application references data in a shared library the size of that
2922 data (whatever its type) is included in the application
2923 executable. If you might want to change the size of an array or
2924 string then provide a pointer not the actual array.
2928 * C header files:: How to write portable include files.
2931 File: libtool.info, Node: C header files, Up: Library tips
2933 8.1 Writing C header files
2934 ==========================
2936 Writing portable C header files can be difficult, since they may be read
2937 by different types of compilers:
2940 C++ compilers require that functions be declared with full
2941 prototypes, since C++ is more strongly typed than C. C functions
2942 and variables also need to be declared with the `extern "C"'
2943 directive, so that the names aren't mangled. *Note C++
2944 libraries::, for other issues relevant to using C++ with libtool.
2947 ANSI C compilers are not as strict as C++ compilers, but functions
2948 should be prototyped to avoid unnecessary warnings when the header
2949 file is `#include'd.
2951 non-ANSI C compilers
2952 Non-ANSI compilers will report errors if functions are prototyped.
2954 These complications mean that your library interface headers must use
2955 some C preprocessor magic in order to be usable by each of the above
2958 `foo.h' in the `tests/demo' subdirectory of the libtool distribution
2959 serves as an example for how to write a header file that can be safely
2960 installed in a system directory.
2962 Here are the relevant portions of that file:
2964 /* BEGIN_C_DECLS should be used at the beginning of your declarations,
2965 so that C++ compilers don't mangle their names. Use END_C_DECLS at
2966 the end of C declarations. */
2967 #undef BEGIN_C_DECLS
2970 # define BEGIN_C_DECLS extern "C" {
2971 # define END_C_DECLS }
2973 # define BEGIN_C_DECLS /* empty */
2974 # define END_C_DECLS /* empty */
2977 /* PARAMS is a macro used to wrap function prototypes, so that
2978 compilers that don't understand ANSI C prototypes still work,
2979 and ANSI C compilers can issue warnings about type mismatches. */
2981 #if defined (__STDC__) || defined (_AIX) \
2982 || (defined (__mips) && defined (_SYSTYPE_SVR4)) \
2983 || defined(WIN32) || defined(__cplusplus)
2984 # define PARAMS(protos) protos
2986 # define PARAMS(protos) ()
2989 These macros are used in `foo.h' as follows:
2994 /* The above macro definitions. */
2999 int foo PARAMS((void));
3000 int hello PARAMS((void));
3006 Note that the `#ifndef FOO_H' prevents the body of `foo.h' from
3007 being read more than once in a given compilation.
3009 Also the only thing that must go outside the
3010 `BEGIN_C_DECLS'/`END_C_DECLS' pair are `#include' lines. Strictly
3011 speaking it is only C symbol names that need to be protected, but your
3012 header files will be more maintainable if you have a single pair of
3013 these macros around the majority of the header contents.
3015 You should use these definitions of `PARAMS', `BEGIN_C_DECLS', and
3016 `END_C_DECLS' into your own headers. Then, you may use them to create
3017 header files that are valid for C++, ANSI, and non-ANSI compilers(1).
3019 Do not be naive about writing portable code. Following the tips
3020 given above will help you miss the most obvious problems, but there are
3021 definitely other subtle portability issues. You may need to cope with
3022 some of the following issues:
3024 * Pre-ANSI compilers do not always support the `void *' generic
3025 pointer type, and so need to use `char *' in its place.
3027 * The `const', `inline' and `signed' keywords are not supported by
3028 some compilers, especially pre-ANSI compilers.
3030 * The `long double' type is not supported by many compilers.
3032 ---------- Footnotes ----------
3034 (1) We used to recommend `__P', `__BEGIN_DECLS' and `__END_DECLS'.
3035 This was bad advice since symbols (even preprocessor macro names) that
3036 begin with an underscore are reserved for the use of the compiler.
3039 File: libtool.info, Node: Inter-library dependencies, Next: Dlopened modules, Prev: Library tips, Up: Top
3041 9 Inter-library dependencies
3042 ****************************
3044 By definition, every shared library system provides a way for
3045 executables to depend on libraries, so that symbol resolution is
3046 deferred until runtime.
3048 An "inter-library dependency" is one in which a library depends on
3049 other libraries. For example, if the libtool library `libhello' uses
3050 the `cos' function, then it has an inter-library dependency on `libm',
3051 the math library that implements `cos'.
3053 Some shared library systems provide this feature in an
3054 internally-consistent way: these systems allow chains of dependencies of
3055 potentially infinite length.
3057 However, most shared library systems are restricted in that they only
3058 allow a single level of dependencies. In these systems, programs may
3059 depend on shared libraries, but shared libraries may not depend on other
3062 In any event, libtool provides a simple mechanism for you to declare
3063 inter-library dependencies: for every library `libNAME' that your own
3064 library depends on, simply add a corresponding `-lNAME' option to the
3065 link line when you create your library. To make an example of our
3066 `libhello' that depends on `libm':
3068 burger$ libtool --mode=link gcc -g -O -o libhello.la foo.lo hello.lo \
3069 -rpath /usr/local/lib -lm
3072 When you link a program against `libhello', you don't need to
3073 specify the same `-l' options again: libtool will do that for you, in
3074 order to guarantee that all the required libraries are found. This
3075 restriction is only necessary to preserve compatibility with static
3076 library systems and simple dynamic library systems.
3078 Some platforms, such as Windows, do not even allow you this
3079 flexibility. In order to build a shared library, it must be entirely
3080 self-contained or it must have dependencies known at link time (that is,
3081 have references only to symbols that are found in the `.lo' files or
3082 the specified `-l' libraries), and you need to specify the
3083 `-no-undefined' flag. By default, libtool builds only static libraries
3084 on these kinds of platforms.
3086 The simple-minded inter-library dependency tracking code of libtool
3087 releases prior to 1.2 was disabled because it was not clear when it was
3088 possible to link one library with another, and complex failures would
3089 occur. A more complex implementation of this concept was re-introduced
3090 before release 1.3, but it has not been ported to all platforms that
3091 libtool supports. The default, conservative behavior is to avoid
3092 linking one library with another, introducing their inter-dependencies
3093 only when a program is linked with them.
3096 File: libtool.info, Node: Dlopened modules, Next: Using libltdl, Prev: Inter-library dependencies, Up: Top
3101 It can sometimes be confusing to discuss "dynamic linking", because the
3102 term is used to refer to two different concepts:
3104 1. Compiling and linking a program against a shared library, which is
3105 resolved automatically at run time by the dynamic linker. In this
3106 process, dynamic linking is transparent to the application.
3108 2. The application calling functions such as `dlopen' that load
3109 arbitrary, user-specified modules at runtime. This type of dynamic
3110 linking is explicitly controlled by the application.
3112 To mitigate confusion, this manual refers to the second type of
3113 dynamic linking as "dlopening" a module.
3115 The main benefit to dlopening object modules is the ability to access
3116 compiled object code to extend your program, rather than using an
3117 interpreted language. In fact, dlopen calls are frequently used in
3118 language interpreters to provide an efficient way to extend the
3121 Libtool provides support for dlopened modules. However, you should
3122 indicate that your package is willing to use such support, by using the
3123 `LT_INIT' option `dlopen' in `configure.ac'. If this option is not
3124 given, libtool will assume no dlopening mechanism is available, and
3125 will try to simulate it.
3127 This chapter discusses how you as a dlopen application developer
3128 might use libtool to generate dlopen-accessible modules.
3132 * Building modules:: Creating dlopenable objects and libraries.
3133 * Dlpreopening:: Dlopening that works on static platforms.
3134 * Linking with dlopened modules:: Using dlopenable modules in libraries.
3135 * Finding the dlname:: Choosing the right file to `dlopen'.
3136 * Dlopen issues:: Unresolved problems that need your attention.
3139 File: libtool.info, Node: Building modules, Next: Dlpreopening, Up: Dlopened modules
3141 10.1 Building modules to dlopen
3142 ===============================
3144 On some operating systems, a program symbol must be specially declared
3145 in order to be dynamically resolved with the `dlsym' (or equivalent)
3146 function. Libtool provides the `-export-dynamic' and `-module' link
3147 flags (*note Link mode::), for you to make that declaration. You need
3148 to use these flags if you are linking an application program that
3149 dlopens other modules or a libtool library that will also be dlopened.
3151 For example, if we wanted to build a shared library, `hello', that
3152 would later be dlopened by an application, we would add `-module' to
3153 the other link flags:
3155 burger$ libtool --mode=link gcc -module -o hello.la foo.lo \
3156 hello.lo -rpath /usr/local/lib -lm
3159 If symbols from your _executable_ are needed to satisfy unresolved
3160 references in a library you want to dlopen you will have to use the flag
3161 `-export-dynamic'. You should use `-export-dynamic' while linking the
3162 executable that calls dlopen:
3164 burger$ libtool --mode=link gcc -export-dynamic -o helldl main.o
3168 File: libtool.info, Node: Dlpreopening, Next: Linking with dlopened modules, Prev: Building modules, Up: Dlopened modules
3173 Libtool provides special support for dlopening libtool object and
3174 libtool library files, so that their symbols can be resolved _even on
3175 platforms without any `dlopen' and `dlsym' functions_.
3177 Consider the following alternative ways of loading code into your
3178 program, in order of increasing "laziness":
3180 1. Linking against object files that become part of the program
3181 executable, whether or not they are referenced. If an object file
3182 cannot be found, then the compile time linker refuses to create
3185 2. Declaring a static library to the linker, so that it is searched
3186 at link time in order to satisfy any undefined references in the
3187 above object files. If the static library cannot be found, then
3188 the compile time linker refuses to create the executable.
3190 3. Declaring a shared library to the runtime linker, so that it is
3191 searched at runtime in order to satisfy any undefined references
3192 in the above files. If the shared library cannot be found, then
3193 the dynamic linker aborts the program before it runs.
3195 4. Dlopening a module, so that the application can resolve its own,
3196 dynamically-computed references. If there is an error opening the
3197 module, or the module is not found, then the application can
3198 recover without crashing.
3200 Libtool emulates `-dlopen' on static platforms by linking objects
3201 into the program at compile time, and creating data structures that
3202 represent the program's symbol table. In order to use this feature,
3203 you must declare the objects you want your application to dlopen by
3204 using the `-dlopen' or `-dlpreopen' flags when you link your program
3205 (*note Link mode::).
3207 -- Data Type: lt_dlsymlist typedef struct { const char *NAME;
3208 void *ADDRESS; } lt_dlsymlist
3209 The NAME attribute is a null-terminated character string of the
3210 symbol name, such as `"fprintf"'. The ADDRESS attribute is a
3211 generic pointer to the appropriate object, such as `&fprintf'.
3213 -- Variable: const lt_dlsymlist lt_preloaded_symbols[]
3214 An array of `lt_dlsymlist' structures, representing all the
3215 preloaded symbols linked into the program proper. For each module
3216 `-dlpreopen'ed by the Libtool linked program there is an element
3217 with the NAME of the module and an ADDRESS of `0', followed by all
3218 symbols exported from this file. For the executable itself the
3219 special name `@PROGRAM@' is used. The last element of all has a
3220 NAME and ADDRESS of `0'.
3222 To facilitate inclusion of symbol lists into libraries,
3223 `lt_preloaded_symbols' is `#define'd to a suitably unique name in
3226 This variable may not be declared `const' on some systems due to
3229 Some compilers may allow identifiers that are not valid in ANSI C,
3230 such as dollar signs. Libtool only recognizes valid ANSI C symbols (an
3231 initial ASCII letter or underscore, followed by zero or more ASCII
3232 letters, digits, and underscores), so non-ANSI symbols will not appear
3233 in `lt_preloaded_symbols'.
3235 -- Function: int lt_dlpreload (const lt_dlsymlist *PRELOADED)
3236 Register the list of preloaded modules PRELOADED. If PRELOADED is
3237 `NULL', then all previously registered symbol lists, except the
3238 list set by `lt_dlpreload_default', are deleted. Return 0 on
3241 -- Function: int lt_dlpreload_default (const lt_dlsymlist *PRELOADED)
3242 Set the default list of preloaded modules to PRELOADED, which
3243 won't be deleted by `lt_dlpreload'. Note that this function does
3244 _not_ require libltdl to be initialized using `lt_dlinit' and can
3245 be used in the program to register the default preloaded modules.
3246 Instead of calling this function directly, most programs will use
3247 the macro `LTDL_SET_PRELOADED_SYMBOLS'.
3249 Return 0 on success.
3251 -- Macro: LTDL_SET_PRELOADED_SYMBOLS
3252 Set the default list of preloaded symbols. Should be used in your
3253 program to initialize libltdl's list of preloaded modules.
3259 LTDL_SET_PRELOADED_SYMBOLS();
3263 -- Function Type: int lt_dlpreload_callback_func (lt_dlhandle HANDLE)
3264 Functions of this type can be passed to `lt_dlpreload_open', which
3265 in turn will call back into a function thus passed for each
3266 preloaded module that it opens.
3268 -- Function: int lt_dlpreload_open (const char *ORIGINATOR,
3269 lt_dlpreload_callback_func *FUNC)
3270 Load all of the preloaded modules for ORIGINATOR. For every
3271 module opened in this way, call FUNC.
3273 To open all of the modules preloaded into `libhell.la' (presumably
3274 from within the `libhell.a' initialisation code):
3276 #define preloaded_symbols lt_libhell_LTX_preloaded_symbols
3278 static int hell_preload_callback (lt_dlhandle handle);
3284 if (lt_dlpreload (&preloaded_symbols) == 0)
3286 lt_dlpreload_open ("libhell", preload_callback);
3291 Note that to prevent clashes between multiple preloaded modules,
3292 the preloaded symbols are accessed via a mangled symbol name: to
3293 get the symbols preloaded into `libhell', you must prefix
3294 `preloaded_symbols' with `lt_'; the originator name, `libhell' in
3295 this case; and `_LTX_'. That is,
3296 `lt_libhell_LTX_preloaded_symbols' here.
3299 File: libtool.info, Node: Linking with dlopened modules, Next: Finding the dlname, Prev: Dlpreopening, Up: Dlopened modules
3301 10.3 Linking with dlopened modules
3302 ==================================
3304 When, say, an interpreter application uses dlopened modules to extend
3305 the list of methods it provides, an obvious abstraction for the
3306 maintainers of the interpreter is to have all methods (including the
3307 built in ones supplied with the interpreter) accessed through dlopen.
3308 For one thing, the dlopening functionality will be tested even during
3309 routine invocations. For another, only one subsystem has to be written
3310 for getting methods into the interpreter.
3312 The downside of this abstraction is, of course, that environments
3313 that provide only static linkage can't even load the intrinsic
3314 interpreter methods. Not so! We can statically link those methods by
3315 *dlpreopening* them.
3317 Unfortunately, since platforms such as AIX and cygwin require that
3318 all library symbols must be resolved at compile time, the interpreter
3319 maintainers will need to provide a library to both its own dlpreopened
3320 modules, and third-party modules loaded by dlopen. In itself, that is
3321 not so bad, except that the interpreter too must provide those same
3322 symbols otherwise it will be impossible to resolve all the symbols
3323 required by the modules as they are loaded. Things are even worse if
3324 the code that loads the modules for the interpreter is itself in a
3325 library - and that is usually the case for any non-trivial application.
3326 Modern platforms take care of this by automatically loading all of a
3327 module's dependency libraries as the module is loaded (libltdl can do
3328 this even on platforms that can't do it by themselves). In the end,
3329 this leads to problems with duplicated symbols and prevents modules
3330 from loading, and prevents the application from compiling when modules
3333 ,-------------. ,------------------. ,-----------------.
3334 | Interpreter |----> Module------------> Third-party |
3335 `-------------' | Loader | |Dlopened Modules |
3336 | | | `-----------------'
3337 |,-------v--------.| |
3340 |`----------------'| |
3342 |,-------v--------.| ,--------v--------.
3343 ||Module Interface|| |Module Interface |
3344 || Library || | Library |
3345 |`----------------'| `-----------------'
3346 `------------------'
3348 Libtool has the concept of "weak library interfaces" to circumvent
3349 this problem. Recall that the code that dlopens method-provider
3350 modules for the interpreter application resides in a library: All of
3351 the modules and the dlopener library itself should be linked against
3352 the common library that resolves the module symbols at compile time.
3353 To guard against duplicate symbol definitions, and for dlpreopened
3354 modules to work at all in this scenario, the dlopener library must
3355 declare that it provides a weak library interface to the common symbols
3356 in the library it shares with the modules. That way, when `libtool'
3357 links the *Module Loader* library with some *Dlpreopened Modules* that
3358 were in turn linked against the *Module Interface Library*, it knows
3359 that the *Module Loader* provides an already loaded *Module Interface
3360 Library* to resolve symbols for the *Dlpreopened Modules*, and doesn't
3361 ask the compiler driver to link an identical *Module Interface Library*
3362 dependency library too.
3364 In conjunction with Automake, the `Makefile.am' for the *Module
3365 Loader* might look like this:
3367 lib_LTLIBRARIES = libinterface.la libloader.la
3369 libinterface_la_SOURCES = interface.c interface.h
3370 libinterface_la_LDFLAGS = -version-info 3:2:1
3372 libloader_la_SOURCES = loader.c
3373 libloader_la_LDFLAGS = -weak libinterface.la \
3374 -version-info 3:2:1 \
3375 -dlpreopen ../modules/intrinsics.la
3376 libloader_la_LIBADD = $(libinterface_la_OBJECTS)
3378 And the `Makefile.am' for the `intrinsics.la' module in a sibling
3379 `modules' directory might look like this:
3381 AM_CPPFLAGS = -I$(srcdir)/../libloader
3382 AM_LDFLAGS = -no-undefined -module -avoid-version \
3385 noinst_LTLIBRARIES = intrinsics.la
3387 intrinsics_la_LIBADD = ../libloader/libinterface.la
3389 ../libloader/libinterface.la:
3390 cd ../libloader && $(MAKE) $(AM_MAKEFLAGS) libinterface.la
3392 For a more complex example, see the sources of `libltdl' in the
3393 Libtool distribution, which is built with the help of the `-weak'
3397 File: libtool.info, Node: Finding the dlname, Next: Dlopen issues, Prev: Linking with dlopened modules, Up: Dlopened modules
3399 10.4 Finding the correct name to dlopen
3400 =======================================
3402 After a library has been linked with `-module', it can be dlopened.
3403 Unfortunately, because of the variation in library names, your package
3404 needs to determine the correct file to dlopen.
3406 The most straightforward and flexible implementation is to determine
3407 the name at runtime, by finding the installed `.la' file, and searching
3408 it for the following lines:
3410 # The name that we can `dlopen'.
3413 If DLNAME is empty, then the library cannot be dlopened. Otherwise,
3414 it gives the dlname of the library. So, if the library was installed
3415 as `/usr/local/lib/libhello.la', and the DLNAME was `libhello.so.3',
3416 then `/usr/local/lib/libhello.so.3' should be dlopened.
3418 If your program uses this approach, then it should search the
3419 directories listed in the `LD_LIBRARY_PATH'(1) environment variable, as
3420 well as the directory where libraries will eventually be installed.
3421 Searching this variable (or equivalent) will guarantee that your
3422 program can find its dlopened modules, even before installation,
3423 provided you have linked them using libtool.
3425 ---------- Footnotes ----------
3427 (1) `LIBPATH' on AIX, and `SHLIB_PATH' on HP-UX.
3430 File: libtool.info, Node: Dlopen issues, Prev: Finding the dlname, Up: Dlopened modules
3432 10.5 Unresolved dlopen issues
3433 =============================
3435 The following problems are not solved by using libtool's dlopen support:
3437 * Dlopen functions are generally only available on shared library
3438 platforms. If you want your package to be portable to static
3439 platforms, you have to use either libltdl (*note Using libltdl::)
3440 or develop your own alternatives to dlopening dynamic code. Most
3441 reasonable solutions involve writing wrapper functions for the
3442 `dlopen' family, which do package-specific tricks when dlopening
3443 is unsupported or not available on a given platform.
3445 * There are major differences in implementations of the `dlopen'
3446 family of functions. Some platforms do not even use the same
3447 function names (notably HP-UX, with its `shl_load' family).
3449 * The application developer must write a custom search function in
3450 order to discover the correct module filename to supply to
3454 File: libtool.info, Node: Using libltdl, Next: Trace interface, Prev: Dlopened modules, Up: Top
3459 Libtool provides a small library, called `libltdl', that aims at hiding
3460 the various difficulties of dlopening libraries from programmers. It
3461 consists of a few headers and small C source files that can be
3462 distributed with applications that need dlopening functionality. On
3463 some platforms, whose dynamic linkers are too limited for a simple
3464 implementation of `libltdl' services, it requires GNU DLD, or it will
3465 only emulate dynamic linking with libtool's dlpreopening mechanism.
3467 libltdl supports currently the following dynamic linking mechanisms:
3469 * `dlopen' (POSIX compliant systems, GNU/Linux, etc.)
3471 * `shl_load' (HP-UX)
3473 * `LoadLibrary' (Win16 and Win32)
3475 * `load_add_on' (BeOS)
3477 * `NSAddImage' or `NSLinkModule' (Darwin and Mac OS X)
3479 * GNU DLD (emulates dynamic linking for static libraries)
3481 * libtool's dlpreopen (see *note Dlpreopening::)
3483 libltdl is licensed under the terms of the GNU Lesser General Public
3484 License, with the following exception:
3486 As a special exception to the GNU Lesser General Public License,
3487 if you distribute this file as part of a program or library that
3488 is built using GNU Libtool, you may include it under the same
3489 distribution terms that you use for the rest of that program.
3493 * Libltdl interface:: How to use libltdl in your programs.
3494 * Modules for libltdl:: Creating modules that can be `dlopen'ed.
3495 * Thread Safety in libltdl:: Registering callbacks for multi-thread safety.
3496 * User defined module data:: Associating data with loaded modules.
3497 * Module loaders for libltdl:: Creating user defined module loaders.
3498 * Distributing libltdl:: How to distribute libltdl with your package.
3501 File: libtool.info, Node: Libltdl interface, Next: Modules for libltdl, Up: Using libltdl
3503 11.1 How to use libltdl in your programs
3504 ========================================
3506 The libltdl API is similar to the POSIX dlopen interface, which is very
3507 simple but powerful.
3509 To use libltdl in your program you have to include the header file
3514 The early releases of libltdl used some symbols that violated the POSIX
3515 namespace conventions. These symbols are now deprecated, and have been
3516 replaced by those described here. If you have code that relies on the
3517 old deprecated symbol names, defining `LT_NON_POSIX_NAMESPACE' before
3518 you include `ltdl.h' provides conversion macros. Whichever set of
3519 symbols you use, the new API is not binary compatible with the last, so
3520 you will need to recompile your application in order to use this
3523 Note that libltdl is not well tested in a multithreaded environment,
3524 though the intention is that it should work (*note Using libltdl in a
3525 multi threaded environment: Thread Safety in libltdl.). It was
3526 reported that GNU/Linux's glibc 2.0's `dlopen' with `RTLD_LAZY' (which
3527 libltdl uses by default) is not thread-safe, but this problem is
3528 supposed to be fixed in glibc 2.1. On the other hand, `RTLD_NOW' was
3529 reported to introduce problems in multi-threaded applications on
3530 FreeBSD. Working around these problems is left as an exercise for the
3531 reader; contributions are certainly welcome.
3533 The following macros are defined by including `ltdl.h':
3535 -- Macro: LT_PATHSEP_CHAR
3536 `LT_PATHSEP_CHAR' is the system-dependent path separator, that is,
3537 `;' on Windows and `:' everywhere else.
3539 -- Macro: LT_DIRSEP_CHAR
3540 If `LT_DIRSEP_CHAR' is defined, it can be used as directory
3541 separator in addition to `/'. On Windows, this contains `\'.
3543 The following types are defined in `ltdl.h':
3545 -- Type: lt_dlhandle
3546 `lt_dlhandle' is a module "handle". Every lt_dlopened module has
3547 a handle associated with it.
3549 -- Type: lt_dladvise
3550 `lt_dladvise' is used to control optional module loading modes.
3551 If it is not used, the default mode of the underlying system module
3554 -- Type: lt_dlsymlist
3555 `lt_dlsymlist' is a symbol list for dlpreopened modules. This
3556 structure is described in *note Dlpreopening::.
3558 libltdl provides the following functions:
3560 -- Function: int lt_dlinit (void)
3561 Initialize libltdl. This function must be called before using
3562 libltdl and may be called several times. Return 0 on success,
3563 otherwise the number of errors.
3565 -- Function: int lt_dlexit (void)
3566 Shut down libltdl and close all modules. This function will only
3567 then shut down libltdl when it was called as many times as
3568 `lt_dlinit' has been successfully called. Return 0 on success,
3569 otherwise the number of errors.
3571 -- Function: lt_dlhandle lt_dlopen (const char *FILENAME)
3572 Open the module with the file name FILENAME and return a handle
3573 for it. `lt_dlopen' is able to open libtool dynamic modules,
3574 preloaded static modules, the program itself and native dynamic
3577 Unresolved symbols in the module are resolved using its dependency
3578 libraries and previously dlopened modules. If the executable using
3579 this module was linked with the `-export-dynamic' flag, then the
3580 global symbols in the executable will also be used to resolve
3581 references in the module.
3583 If FILENAME is `NULL' and the program was linked with
3584 `-export-dynamic' or `-dlopen self', `lt_dlopen' will return a
3585 handle for the program itself, which can be used to access its
3588 If libltdl cannot find the library and the file name FILENAME does
3589 not have a directory component it will additionally look in the
3590 following search paths for the module (in the following order):
3592 1. user-defined search path: This search path can be changed by
3593 the program using the functions `lt_dlsetsearchpath',
3594 `lt_dladdsearchdir' and `lt_dlinsertsearchdir'.
3596 2. libltdl's search path: This search path is the value of the
3597 environment variable `LTDL_LIBRARY_PATH'.
3599 3. system library search path: The system dependent library
3600 search path (e.g. on GNU/Linux it is `LD_LIBRARY_PATH').
3602 Each search path must be a list of absolute directories separated
3603 by `LT_PATHSEP_CHAR', for example, `"/usr/lib/mypkg:/lib/foo"'.
3604 The directory names may not contain the path separator.
3606 If the same module is loaded several times, the same handle is
3607 returned. If `lt_dlopen' fails for any reason, it returns `NULL'.
3609 -- Function: lt_dlhandle lt_dlopenext (const char *FILENAME)
3610 The same as `lt_dlopen', except that it tries to append different
3611 file name extensions to the file name. If the file with the file
3612 name FILENAME cannot be found libltdl tries to append the
3613 following extensions:
3615 1. the libtool archive extension `.la'
3617 2. the extension used for native dynamically loadable modules on
3618 the host platform, e.g., `.so', `.sl', etc.
3620 This lookup strategy was designed to allow programs that don't
3621 have knowledge about native dynamic libraries naming conventions
3622 to be able to `dlopen' such libraries as well as libtool modules
3625 -- Function: lt_dlhandle lt_dlopenadvise (const char *FILENAME,
3627 The same as `lt_dlopen', except that it also requires an additional
3628 argument which may contain additional hints to the underlying
3629 system module loader. The ADVISE parameter is opaque and can only
3630 be accessed with the functions documented below.
3632 Note that this function does not change the content of ADVISE, so
3633 unlike the other calls in this API takes a direct `lt_dladvise'
3634 type, and not a pointer to the same.
3636 -- Function: int lt_dladvise_init (lt_dladvise *ADVISE)
3637 The ADVISE parameter can be used to pass hints to the module
3638 loader when using `lt_dlopenadvise' to perform the loading. The
3639 ADVISE parameter needs to be initialised by this function before
3640 it can be used. Any memory used by ADVISE needs to be recycled
3641 with `lt_dladvise_destroy' when it is no longer needed.
3643 On failure, `lt_dladvise_init' returns non-zero and sets an error
3644 message that can be retrieved with `lt_dlerror'.
3646 -- Function: int lt_dladvise_destroy (lt_dladvise *ADVISE)
3647 Recycle the memory used by ADVISE. For an example, see the
3648 documentation for `lt_dladvise_ext'.
3650 On failure, `lt_dladvise_destroy' returns non-zero and sets an
3651 error message that can be retrieved with `lt_dlerror'.
3653 -- Function: int lt_dladvise_ext (lt_dladvise *ADVISE)
3654 Set the `ext' hint on ADVISE. Passing an ADVISE parameter to
3655 `lt_dlopenadvise' with this hint set causes it to try to append
3656 different file name extensions like `lt_dlopenext'.
3658 The following example is equivalent to calling `lt_dlopenext
3662 my_dlopenext (const char *filename)
3664 lt_dlhandle handle = 0;
3667 if (!lt_dladvise_init (&advise) && !lt_dladvise_ext (&advise))
3668 handle = lt_dlopenadvise (filename, advise);
3670 lt_dladvise_destroy (&advise);
3675 On failure, `lt_dladvise_ext' returns non-zero and sets an error
3676 message that can be retrieved with `lt_dlerror'.
3678 -- Function: int lt_dladvise_global (lt_dladvise *ADVISE)
3679 Set the `symglobal' hint on ADVISE. Passing an ADVISE parameter
3680 to `lt_dlopenadvise' with this hint set causes it to try to make
3681 the loaded module's symbols globally available for resolving
3682 unresolved symbols in subsequently loaded modules.
3684 If neither the `symglobal' nor the `symlocal' hints are set, or if
3685 a module is loaded without using the `lt_dlopenadvise' call in any
3686 case, then the visibility of the module's symbols will be as per
3687 the default for the underlying module loader and OS. Even if a
3688 suitable hint is passed, not all loaders are able to act upon it in
3689 which case `lt_dlgetinfo' will reveal whether the hint was actually
3692 On failure, `lt_dladvise_global' returns non-zero and sets an error
3693 message that can be retrieved with `lt_dlerror'.
3695 -- Function: int lt_dladvise_local (lt_dladvise *ADVISE)
3696 Set the `symlocal' hint on ADVISE. Passing an ADVISE parameter to
3697 `lt_dlopenadvise' with this hint set causes it to try to keep the
3698 loaded module's symbols hidden so that they are not visible to
3699 subsequently loaded modules.
3701 If neither the `symglobal' nor the `symlocal' hints are set, or if
3702 a module is loaded without using the `lt_dlopenadvise' call in any
3703 case, then the visibility of the module's symbols will be as per
3704 the default for the underlying module loader and OS. Even if a
3705 suitable hint is passed, not all loaders are able to act upon it in
3706 which case `lt_dlgetinfo' will reveal whether the hint was actually
3709 On failure, `lt_dladvise_local' returns non-zero and sets an error
3710 message that can be retrieved with `lt_dlerror'.
3712 -- Function: int lt_dladvise_resident (lt_dladvise *ADVISE)
3713 Set the `resident' hint on ADVISE. Passing an ADVISE parameter to
3714 `lt_dlopenadvise' with this hint set causes it to try to make the
3715 loaded module resident in memory, so that it cannot be unloaded
3716 with a later call to `lt_dlclose'.
3718 On failure, `lt_dladvise_resident' returns non-zero and sets an
3719 error message that can be retrieved with `lt_dlerror'.
3721 -- Function: int lt_dladvise_preload (lt_dladvise *ADVISE)
3722 Set the `preload' hint on ADVISE. Passing an ADVISE parameter to
3723 `lt_dlopenadvise' with this hint set causes it to load only
3724 preloaded modules, so that if a suitable preloaded module is not
3725 found, `lt_dlopenadvise' will return `NULL'.
3727 -- Function: int lt_dlclose (lt_dlhandle HANDLE)
3728 Decrement the reference count on the module HANDLE. If it drops
3729 to zero and no other module depends on this module, then the
3730 module is unloaded. Return 0 on success.
3732 -- Function: void * lt_dlsym (lt_dlhandle HANDLE, const char *NAME)
3733 Return the address in the module HANDLE, where the symbol given by
3734 the null-terminated string NAME is loaded. If the symbol cannot
3735 be found, `NULL' is returned.
3737 -- Function: const char * lt_dlerror (void)
3738 Return a human readable string describing the most recent error
3739 that occurred from any of libltdl's functions. Return `NULL' if
3740 no errors have occurred since initialization or since it was last
3743 -- Function: int lt_dladdsearchdir (const char *SEARCH_DIR)
3744 Append the search directory SEARCH_DIR to the current user-defined
3745 library search path. Return 0 on success.
3747 -- Function: int lt_dlinsertsearchdir (const char *BEFORE,
3748 const char *SEARCH_DIR)
3749 Insert the search directory SEARCH_DIR into the user-defined
3750 library search path, immediately before the element starting at
3751 address BEFORE. If BEFORE is `NULL', then SEARCH_DIR is appending
3752 as if `lt_dladdsearchdir' had been called. Return 0 on success.
3754 -- Function: int lt_dlsetsearchpath (const char *SEARCH_PATH)
3755 Replace the current user-defined library search path with
3756 SEARCH_PATH, which must be a list of absolute directories separated
3757 by `LT_PATHSEP_CHAR'. Return 0 on success.
3759 -- Function: const char * lt_dlgetsearchpath (void)
3760 Return the current user-defined library search path.
3762 -- Function: int lt_dlforeachfile (const char *SEARCH_PATH,
3763 int (*FUNC) (const char *FILENAME, void * DATA), void * DATA)
3764 In some applications you may not want to load individual modules
3765 with known names, but rather find all of the modules in a set of
3766 directories and load them all during initialisation. With this
3767 function you can have libltdl scan the `LT_PATHSEP_CHAR'-delimited
3768 directory list in SEARCH_PATH for candidates, and pass them, along
3769 with DATA to your own callback function, FUNC. If SEARCH_PATH is
3770 `NULL', then search all of the standard locations that `lt_dlopen'
3771 would examine. This function will continue to make calls to FUNC
3772 for each file that it discovers in SEARCH_PATH until one of these
3773 calls returns non-zero, or until the files are exhausted.
3774 `lt_dlforeachfile' returns the value returned by the last call
3777 For example you could define FUNC to build an ordered "argv"-like
3778 vector of files using DATA to hold the address of the start of the
3781 -- Function: int lt_dlmakeresident (lt_dlhandle HANDLE)
3782 Mark a module so that it cannot be `lt_dlclose'd. This can be
3783 useful if a module implements some core functionality in your
3784 project that would cause your code to crash if removed. Return 0
3787 If you use `lt_dlopen (NULL)' to get a HANDLE for the running
3788 binary, that handle will always be marked as resident, and
3789 consequently cannot be successfully `lt_dlclose'd.
3791 -- Function: int lt_dlisresident (lt_dlhandle HANDLE)
3792 Check whether a particular module has been marked as resident,
3793 returning 1 if it has or 0 otherwise. If there is an error while
3794 executing this function, return -1 and set an error message for
3795 retrieval with `lt_dlerror'.
3797 ---------- Footnotes ----------
3799 (1) Some platforms, notably Mac OS X, differentiate between a
3800 runtime library that cannot be opened by `lt_dlopen' and a dynamic
3801 module that can. For maximum portability you should try to ensure that
3802 you only pass `lt_dlopen' objects that have been compiled with libtool's
3806 File: libtool.info, Node: Modules for libltdl, Next: Thread Safety in libltdl, Prev: Libltdl interface, Up: Using libltdl
3808 11.2 Creating modules that can be `dlopen'ed
3809 ============================================
3811 Libtool modules are created like normal libtool libraries with a few
3814 You have to link the module with libtool's `-module' switch, and you
3815 should link any program that is intended to dlopen the module with
3816 `-dlopen MODULENAME.LA' where possible, so that libtool can dlpreopen
3817 the module on platforms that do not support dlopening. If the module
3818 depends on any other libraries, make sure you specify them either when
3819 you link the module or when you link programs that dlopen it. If you
3820 want to disable versioning (*note Versioning::) for a specific module
3821 you should link it with the `-avoid-version' switch. Note that libtool
3822 modules don't need to have a "lib" prefix. However, Automake 1.4 or
3823 higher is required to build such modules.
3825 Usually a set of modules provide the same interface, i.e. exports
3826 the same symbols, so that a program can dlopen them without having to
3827 know more about their internals: In order to avoid symbol conflicts all
3828 exported symbols must be prefixed with "modulename_LTX_" (MODULENAME is
3829 the name of the module). Internal symbols must be named in such a way
3830 that they won't conflict with other modules, for example, by prefixing
3831 them with "_modulename_". Although some platforms support having the
3832 same symbols defined more than once it is generally not portable and it
3833 makes it impossible to dlpreopen such modules.
3835 libltdl will automatically cut the prefix off to get the real name of
3836 the symbol. Additionally, it supports modules that do not use a prefix
3837 so that you can also dlopen non-libtool modules.
3839 `foo1.c' gives an example of a portable libtool module. Exported
3840 symbols are prefixed with "foo1_LTX_", internal symbols with "_foo1_".
3841 Aliases are defined at the beginning so that the code is more readable.
3843 /* aliases for the exported symbols */
3844 #define foo foo1_LTX_foo
3845 #define bar foo1_LTX_bar
3847 /* a global variable definition */
3850 /* a private function */
3851 int _foo1_helper() {
3855 /* an exported function */
3857 return _foo1_helper();
3860 The `Makefile.am' contains the necessary rules to build the module
3864 lib_LTLIBRARIES = foo1.la
3866 foo1_la_SOURCES = foo1.c
3867 foo1_la_LDFLAGS = -module
3871 File: libtool.info, Node: Thread Safety in libltdl, Next: User defined module data, Prev: Modules for libltdl, Up: Using libltdl
3873 11.3 Using libltdl in a multi threaded environment
3874 ==================================================
3876 Libltdl provides a wrapper around whatever dynamic run-time object
3877 loading mechanisms are provided by the host system, many of which are
3878 themselves not thread safe. Consequently libltdl cannot itself be
3879 consistently thread safe.
3881 If you wish to use libltdl in a multithreaded environment, then you
3882 must mutex lock around libltdl calls, since they may in turn be calling
3883 non-thread-safe system calls on some target hosts.
3885 Some old releases of libtool provided a mutex locking API that was
3886 unusable with POSIX threads, so callers were forced to lock around all
3887 libltdl API calls anyway. That mutex locking API was next to useless,
3888 and is not present in current releases.
3890 Some future release of libtool may provide a new POSIX thread
3891 compliant mutex locking API.
3894 File: libtool.info, Node: User defined module data, Next: Module loaders for libltdl, Prev: Thread Safety in libltdl, Up: Using libltdl
3896 11.4 Data associated with loaded modules
3897 ========================================
3899 Some of the internal information about each loaded module that is
3900 maintained by libltdl is available to the user, in the form of this
3903 -- Type: struct lt_dlinfo { char *FILENAME; char *NAME; int REF_COUNT;
3904 int IS_RESIDENT; int IS_SYMGLOBAL; int IS_SYMLOCAL;}
3905 `lt_dlinfo' is used to store information about a module. The
3906 FILENAME attribute is a null-terminated character string of the
3907 real module file name. If the module is a libtool module then
3908 NAME is its module name (e.g. `"libfoo"' for `"dir/libfoo.la"'),
3909 otherwise it is set to `NULL'. The REF_COUNT attribute is a
3910 reference counter that describes how often the same module is
3911 currently loaded. The remaining fields can be compared to any
3912 hints that were passed to `lt_dlopenadvise' to determine whether
3913 the underlying loader was able to follow them.
3915 The following function will return a pointer to libltdl's internal
3916 copy of this structure for the given HANDLE:
3918 -- Function: const lt_dlinfo * lt_dlgetinfo (lt_dlhandle HANDLE)
3919 Return a pointer to a struct that contains some information about
3920 the module HANDLE. The contents of the struct must not be
3921 modified. Return `NULL' on failure.
3923 Furthermore, in order to save you from having to keep a list of the
3924 handles of all the modules you have loaded, these functions allow you to
3925 iterate over libltdl's list of loaded modules:
3927 -- Type: lt_dlinterface_id
3928 The opaque type used to hold the module interface details for each
3929 registered libltdl client.
3931 -- Type: int lt_dlhandle_interface (lt_dlhandle HANDLE,
3932 const char *ID_STRING)
3933 Functions of this type are called to check that a handle conforms
3934 to a library's expected module interface when iterating over the
3935 global handle list. You should be careful to write a callback
3936 function of this type that can correctly identify modules that
3937 belong to this client, both to prevent other clients from
3938 accidentally finding your loaded modules with the iterator
3939 functions below, and vice versa. The best way to do this is to
3940 check that module HANDLE conforms to the interface specification
3941 of your loader using `lt_dlsym'.
3943 The callback may be given *every* module loaded by all the libltdl
3944 module clients in the current address space, including any modules
3945 loaded by other libraries such as libltdl itself, and should
3946 return non-zero if that module does not fulfill the interface
3947 requirements of your loader.
3950 my_interface_cb (lt_dlhandle handle, const char *id_string)
3952 char *(*module_id) (void) = NULL;
3954 /* A valid my_module must provide all of these symbols. */
3955 if (!((module_id = (char*(*)(void)) lt_dlsym ("module_version"))
3956 && lt_dlsym ("my_module_entrypoint")))
3959 if (strcmp (id_string, module_id()) != 0)
3965 -- Function: lt_dlinterface_id lt_dlinterface_register
3966 (const char *ID_STRING, lt_dlhandle_interface *IFACE)
3967 Use this function to register your interface validator with
3968 libltdl, and in return obtain a unique key to store and retrieve
3969 per-module data. You supply an ID_STRING and IFACE so that the
3970 resulting `lt_dlinterface_id' can be used to filter the module
3971 handles returned by the iteration functions below. If IFACE is
3972 `NULL', all modules will be matched.
3974 -- Function: void lt_dlinterface_free (lt_dlinterface_id IFACE)
3975 Release the data associated with IFACE.
3977 -- Function: int lt_dlhandle_map (lt_dlinterface_id IFACE,
3978 int (*FUNC) (lt_dlhandle HANDLE, void * DATA), void * DATA)
3979 For each module that matches IFACE, call the function FUNC. When
3980 writing the FUNC callback function, the argument HANDLE is the
3981 handle of a loaded module, and DATA is the last argument passed to
3982 `lt_dlhandle_map'. As soon as FUNC returns a non-zero value for
3983 one of the handles, `lt_dlhandle_map' will stop calling FUNC and
3984 immediately return that non-zero value. Otherwise 0 is eventually
3985 returned when FUNC has been successfully called for all matching
3988 -- Function: lt_dlhandle lt_dlhandle_iterate
3989 (lt_dlinterface_id IFACE, lt_dlhandle PLACE)
3990 Iterate over the module handles loaded by IFACE, returning the
3991 first matching handle in the list if PLACE is `NULL', and the next
3992 one on subsequent calls. If PLACE is the last element in the list
3993 of eligible modules, this function returns `NULL'.
3995 lt_dlhandle handle = 0;
3996 lt_dlinterface_id iface = my_interface_id;
3998 while ((handle = lt_dlhandle_iterate (iface, handle)))
4003 -- Function: lt_dlhandle lt_dlhandle_fetch (lt_dlinterface_id IFACE,
4004 const char *MODULE_NAME)
4005 Search through the module handles loaded by IFACE for a module
4006 named MODULE_NAME, returning its handle if found or else `NULL' if
4007 no such named module has been loaded by IFACE.
4009 However, you might still need to maintain your own list of loaded
4010 module handles (in parallel with the list maintained inside libltdl) if
4011 there were any other data that your application wanted to associate
4012 with each open module. Instead, you can use the following API calls to
4013 do that for you. You must first obtain a unique interface id from
4014 libltdl as described above, and subsequently always use it to retrieve
4015 the data you stored earlier. This allows different libraries to each
4016 store their own data against loaded modules, without interfering with
4019 -- Function: void * lt_dlcaller_set_data (lt_dlinterface_id KEY,
4020 lt_dlhandle HANDLE, void * DATA)
4021 Set DATA as the set of data uniquely associated with KEY and
4022 HANDLE for later retrieval. This function returns the DATA
4023 previously associated with KEY and HANDLE if any. A result of 0,
4024 may indicate that a diagnostic for the last error (if any) is
4025 available from `lt_dlerror()'.
4027 For example, to correctly remove some associated data:
4029 void *stale = lt_dlcaller_set_data (key, handle, 0);
4036 char *error_msg = lt_dlerror ();
4038 if (error_msg != NULL)
4040 my_error_handler (error_msg);
4041 return STATUS_FAILED;
4045 -- Function: void * lt_dlcaller_get_data (lt_dlinterface_id KEY,
4047 Return the address of the data associated with KEY and HANDLE, or
4048 else `NULL' if there is none.
4050 Old versions of libltdl also provided a simpler, but similar, API
4051 based around `lt_dlcaller_id'. Unfortunately, it had no provision for
4052 detecting whether a module belonged to a particular interface as
4053 libltdl didn't support multiple loaders in the same address space at
4054 that time. Those APIs are no longer supported as there would be no way
4055 to stop clients of the old APIs from seeing (and accidentally altering)
4056 modules loaded by other libraries.
4059 File: libtool.info, Node: Module loaders for libltdl, Next: Distributing libltdl, Prev: User defined module data, Up: Using libltdl
4061 11.5 How to create and register new module loaders
4062 ==================================================
4064 Sometimes libltdl's many ways of gaining access to modules are not
4065 sufficient for the purposes of a project. You can write your own
4066 loader, and register it with libltdl so that `lt_dlopen' will be able
4069 Writing a loader involves writing at least three functions that can
4070 be called by `lt_dlopen', `lt_dlsym' and `lt_dlclose'. Optionally, you
4071 can provide a finalisation function to perform any cleanup operations
4072 when `lt_dlexit' executes, and a symbol prefix string that will be
4073 prepended to any symbols passed to `lt_dlsym'. These functions must
4074 match the function pointer types below, after which they can be
4075 allocated to an instance of `lt_user_dlloader' and registered.
4077 Registering the loader requires that you choose a name for it, so
4078 that it can be recognised by `lt_dlloader_find' and removed with
4079 `lt_dlloader_remove'. The name you choose must be unique, and not
4080 already in use by libltdl's builtin loaders:
4083 The system dynamic library loader, if one exists.
4086 The GNU dld loader, if `libdld' was installed when libltdl was
4090 The loader for `lt_dlopen'ing of preloaded static modules.
4092 The prefix "dl" is reserved for loaders supplied with future
4093 versions of libltdl, so you should not use that for your own loader
4096 The following types are defined in `ltdl.h':
4099 `lt_module' is a dlloader dependent module. The dynamic module
4100 loader extensions communicate using these low level types.
4102 -- Type: lt_dlloader
4103 `lt_dlloader' is a handle for module loader types.
4105 -- Type: lt_user_data
4106 `lt_user_data' is used for specifying loader instance data.
4108 -- Type: struct lt_user_dlloader {const char *SYM_PREFIX;
4109 lt_module_open *MODULE_OPEN; lt_module_close *MODULE_CLOSE;
4110 lt_find_sym *FIND_SYM; lt_dlloader_exit *DLLOADER_EXIT; }
4111 If you want to define a new way to open dynamic modules, and have
4112 the `lt_dlopen' API use it, you need to instantiate one of these
4113 structures and pass it to `lt_dlloader_add'. You can pass whatever
4114 you like in the DLLOADER_DATA field, and it will be passed back as
4115 the value of the first parameter to each of the functions
4116 specified in the function pointer fields.
4118 -- Type: lt_module lt_module_open (const char *FILENAME)
4119 The type of the loader function for an `lt_dlloader' module
4120 loader. The value set in the dlloader_data field of the `struct
4121 lt_user_dlloader' structure will be passed into this function in
4122 the LOADER_DATA parameter. Implementation of such a function
4123 should attempt to load the named module, and return an `lt_module'
4124 suitable for passing in to the associated `lt_module_close' and
4125 `lt_sym_find' function pointers. If the function fails it should
4126 return `NULL', and set the error message with `lt_dlseterror'.
4128 -- Type: int lt_module_close (lt_user_data LOADER_DATA,
4130 The type of the unloader function for a user defined module loader.
4131 Implementation of such a function should attempt to release any
4132 resources tied up by the MODULE module, and then unload it from
4133 memory. If the function fails for some reason, set the error
4134 message with `lt_dlseterror' and return non-zero.
4136 -- Type: void * lt_find_sym (lt_module MODULE, const char *SYMBOL)
4137 The type of the symbol lookup function for a user defined module
4138 loader. Implementation of such a function should return the
4139 address of the named SYMBOL in the module MODULE, or else set the
4140 error message with `lt_dlseterror' and return `NULL' if lookup
4143 -- Type: int lt_dlloader_exit (lt_user_data LOADER_DATA)
4144 The type of the finalisation function for a user defined module
4145 loader. Implementation of such a function should free any
4146 resources associated with the loader, including any user specified
4147 data in the `dlloader_data' field of the `lt_user_dlloader'. If
4148 non-`NULL', the function will be called by `lt_dlexit', and
4149 `lt_dlloader_remove'.
4154 register_myloader (void)
4156 lt_user_dlloader dlloader;
4158 /* User modules are responsible for their own initialisation. */
4159 if (myloader_init () != 0)
4160 return MYLOADER_INIT_ERROR;
4162 dlloader.sym_prefix = NULL;
4163 dlloader.module_open = myloader_open;
4164 dlloader.module_close = myloader_close;
4165 dlloader.find_sym = myloader_find_sym;
4166 dlloader.dlloader_exit = myloader_exit;
4167 dlloader.dlloader_data = (lt_user_data)myloader_function;
4169 /* Add my loader as the default module loader. */
4170 if (lt_dlloader_add (lt_dlloader_next (NULL), &dlloader,
4177 Note that if there is any initialisation required for the loader, it
4178 must be performed manually before the loader is registered - libltdl
4179 doesn't handle user loader initialisation.
4181 Finalisation _is_ handled by libltdl however, and it is important to
4182 ensure the `dlloader_exit' callback releases any resources claimed
4183 during the initialisation phase.
4185 libltdl provides the following functions for writing your own module
4188 -- Function: int lt_dlloader_add (lt_dlloader *PLACE,
4189 lt_user_dlloader *DLLOADER, const char *LOADER_NAME)
4190 Add a new module loader to the list of all loaders, either as the
4191 last loader (if PLACE is `NULL'), else immediately before the
4192 loader passed as PLACE. LOADER_NAME will be returned by
4193 `lt_dlloader_name' if it is subsequently passed a newly registered
4194 loader. These LOADER_NAMEs must be unique, or
4195 `lt_dlloader_remove' and `lt_dlloader_find' cannot work. Returns
4198 /* Make myloader be the last one. */
4199 if (lt_dlloader_add (NULL, myloader) != 0)
4200 perror (lt_dlerror ());
4202 -- Function: int lt_dlloader_remove (const char *LOADER_NAME)
4203 Remove the loader identified by the unique name, LOADER_NAME.
4204 Before this can succeed, all modules opened by the named loader
4205 must have been closed. Returns 0 for success, otherwise an error
4206 message can be obtained from `lt_dlerror'.
4208 /* Remove myloader. */
4209 if (lt_dlloader_remove ("myloader") != 0)
4210 perror (lt_dlerror ());
4212 -- Function: lt_dlloader * lt_dlloader_next (lt_dlloader *PLACE)
4213 Iterate over the module loaders, returning the first loader if
4214 PLACE is `NULL', and the next one on subsequent calls. The handle
4215 is for use with `lt_dlloader_add'.
4217 /* Make myloader be the first one. */
4218 if (lt_dlloader_add (lt_dlloader_next (NULL), myloader) != 0)
4221 -- Function: lt_dlloader * lt_dlloader_find (const char *LOADER_NAME)
4222 Return the first loader with a matching LOADER_NAME identifier, or
4223 else `NULL', if the identifier is not found.
4225 The identifiers that may be used by libltdl itself, if the host
4226 architecture supports them are "dlopen"(1), "dld" and "dlpreload".
4228 /* Add a user loader as the next module loader to be tried if
4229 the standard dlopen loader were to fail when lt_dlopening. */
4230 if (lt_dlloader_add (lt_dlloader_find ("dlopen"), myloader) != 0)
4233 -- Function: const char * lt_dlloader_name (lt_dlloader *PLACE)
4234 Return the identifying name of PLACE, as obtained from
4235 `lt_dlloader_next' or `lt_dlloader_find'. If this function fails,
4236 it will return `NULL' and set an error for retrieval with
4239 -- Function: lt_user_data * lt_dlloader_data (lt_dlloader *PLACE)
4240 Return the address of the `dlloader_data' of PLACE, as obtained
4241 from `lt_dlloader_next' or `lt_dlloader_find'. If this function
4242 fails, it will return `NULL' and set an error for retrieval with
4245 11.5.1 Error handling within user module loaders
4246 ------------------------------------------------
4248 -- Function: int lt_dladderror (const char *DIAGNOSTIC)
4249 This function allows you to integrate your own error messages into
4250 `lt_dlerror'. Pass in a suitable diagnostic message for return by
4251 `lt_dlerror', and an error identifier for use with `lt_dlseterror'
4254 If the allocation of an identifier fails, this function returns -1.
4256 int myerror = lt_dladderror ("Doh!");
4258 perror (lt_dlerror ());
4260 -- Function: int lt_dlseterror (int ERRORCODE)
4261 When writing your own module loaders, you should use this function
4262 to raise errors so that they are propagated through the
4263 `lt_dlerror' interface. All of the standard errors used by
4264 libltdl are declared in `ltdl.h', or you can add more of your own
4265 with `lt_dladderror'. This function returns 0 on success.
4267 if (lt_dlseterror (LTDL_ERROR_NO_MEMORY) != 0)
4268 perror (lt_dlerror ());
4270 ---------- Footnotes ----------
4272 (1) This is used for the host dependent module loading API -
4273 `shl_load' and `LoadLibrary' for example
4276 File: libtool.info, Node: Distributing libltdl, Prev: Module loaders for libltdl, Up: Using libltdl
4278 11.6 How to distribute libltdl with your package
4279 ================================================
4281 Even though libltdl is installed together with libtool, you may wish to
4282 include libltdl in the distribution of your package, for the
4283 convenience of users of your package that don't have libtool or libltdl
4284 installed, or if you are using features of a very new version of
4285 libltdl that you don't expect your users to have yet. In such cases,
4286 you must decide which flavor of libltdl you want to use: a convenience
4287 library or an installable libtool library.
4289 The most simplistic way to add `libltdl' to your package is to copy
4290 all the `libltdl' source files to a subdirectory within your package
4291 and to build and link them along with the rest of your sources. To
4292 help you do this, the m4 macros for Autoconf are available in
4293 `ltdl.m4'. You must ensure that they are available in `aclocal.m4'
4294 before you run Autoconf(1). Having made the macros available, you must
4295 add a call to the `LTDL_INIT' macro (after the call to `LT_INIT') to
4296 your package's `configure.ac' to perform the configure time checks
4297 required to build the library correctly. Unfortunately, this method
4298 has problems if you then try to link the package binaries with an
4299 installed libltdl, or a library that depends on libltdl, because of the
4300 duplicate symbol definitions. For example, ultimately linking against
4301 two different versions of libltdl, or against both a local convenience
4302 library and an installed libltdl is bad. Ensuring that only one copy
4303 of the libltdl sources are linked into any program is left as an
4304 exercise for the reader.
4306 -- Macro: LT_CONFIG_LTDL_DIR (DIRECTORY)
4307 Declare DIRECTORY to be the location of the `libltdl' source
4308 files, for `libtoolize --ltdl' to place them. *Note Invoking
4309 libtoolize::, for more details. Provided that you add an
4310 appropriate `LT_CONFIG_LTDL_DIR' call in your `configure.ac'
4311 before calling `libtoolize', the appropriate `libltdl' files will
4312 be installed automatically.
4314 -- Macro: LTDL_INIT (OPTIONS)
4315 -- Macro: LT_WITH_LTDL
4316 -- Macro: AC_WITH_LTDL
4317 `AC_WITH_LTDL' and `LT_WITH_LTDL' are deprecated names for older
4318 versions of this macro; `autoupdate' will update your
4319 `configure.ac' file.
4321 This macro adds the following options to the `configure' script:
4323 `--with-ltdl-include INSTALLED-LTDL-HEADER-DIR'
4324 The `LTDL_INIT' macro will look in the standard header file
4325 locations to find the installed `libltdl' headers. If
4326 `LTDL_INIT' can't find them by itself, the person who builds
4327 your package can use this option to tell `configure' where
4328 the installed `libltdl' headers are.
4330 `--with-ltdl-lib INSTALLED-LTDL-LIBRARY-DIR'
4331 Similarly, the person building your package can use this
4332 option to help `configure' find the installed `libltdl.la'.
4334 `--with-included-ltdl'
4335 If there is no installed `libltdl', or in any case if the
4336 person building your package would rather use the `libltdl'
4337 sources shipped with the package in the subdirectory named by
4338 `LT_CONFIG_LTDL_DIR', they should pass this option to
4341 If the `--with-included-ltdl' is not passed at configure time, and
4342 an installed `libltdl' is not found(2), then `configure' will exit
4343 immediately with an error that asks the user to either specify the
4344 location of an installed `libltdl' using the `--with-ltdl-include'
4345 and `--with-ltdl-lib' options, or to build with the `libltdl'
4346 sources shipped with the package by passing `--with-included-ltdl'.
4348 If an installed `libltdl' is found, then `LIBLTDL' is set to the
4349 link flags needed to use it, and `LTDLINCL' to the preprocessor
4350 flags needed to find the installed headers, and `LTDLDEPS' will be
4351 empty. Note, however, that no version checking is performed. You
4352 should manually check for the `libltdl' features you need in
4358 # The lt_dladvise_init symbol was added with libtool-2.2
4359 if test "x$with_included_ltdl" != "xyes"; then
4360 save_CFLAGS="$CFLAGS"
4361 save_LDFLAGS="$LDFLAGS"
4362 CFLAGS="$CFLAGS $LTDLINCL"
4363 LDFLAGS="$LDFLAGS $LIBLTDL"
4364 AC_CHECK_LIB([ltdl], [lt_dladvise_init],
4366 [AC_MSG_ERROR([installed libltdl is too old])])
4367 LDFLAGS="$save_LDFLAGS"
4368 CFLAGS="$save_CFLAGS"
4371 OPTIONS may include no more than one of the following build modes
4372 depending on how you want your project to build `libltdl':
4373 `nonrecursive', `recursive', or `subproject'. In order for
4374 `libtoolize' to detect this option correctly, if you supply one of
4375 these arguments, they must be given literally (i.e., macros or
4376 shell variables that expand to the correct ltdl mode will not
4380 This is how the Libtool project distribution builds the
4381 `libltdl' we ship and install. If you wish to use Automake
4382 to build `libltdl' without invoking a recursive make to
4383 descend into the `libltdl' subdirectory, then use this
4384 option. You will need to set your configuration up carefully
4385 to make this work properly, and you will need releases of
4386 Autoconf and Automake that support `subdir-objects' and
4387 `LIBOBJDIR' properly. In your `configure.ac', add:
4389 AM_INIT_AUTOMAKE([subdir-objects])
4390 AC_CONFIG_HEADERS([config.h])
4391 LT_CONFIG_LTDL_DIR([libltdl])
4393 LTDL_INIT([nonrecursive])
4395 You _have to_ use a config header, but it may have a name
4396 different than `config.h'.
4398 Also, add the following near the top of your `Makefile.am':
4409 noinst_LTLIBRARIES =
4413 include libltdl/Makefile.inc
4415 Unless you build no other libraries from this `Makefile.am',
4416 you will also need to change `lib_LTLIBRARIES' to assign with
4417 `+=' so that the `libltdl' targets declared in `Makefile.inc'
4418 are not overwritten.
4421 This build mode still requires that you use Automake, but (in
4422 contrast with `nonrecursive') uses the more usual device of
4423 starting another `make' process in the `libltdl'
4424 subdirectory. To use this mode, you should add to your
4428 AC_CONFIG_HEADERS([config.h])
4429 LT_CONFIG_LTDL_DIR([libltdl])
4431 LTDL_INIT([recursive])
4432 AC_CONFIG_FILES([libltdl/Makefile])
4434 Again, you _have to_ use a config header, but it may have a
4435 name different than `config.h' if you like.
4437 Also, add this to your `Makefile.am':
4442 This mode is the default unless you explicitly add
4443 `recursive' or `nonrecursive' to your `LTDL_INIT' options;
4444 `subproject' is the only mode supported by previous releases
4445 of libltdl. Even if you do not use Autoconf in the parent
4446 project, then, in `subproject' mode, still `libltdl' contains
4447 all the necessary files to configure and build itself - you
4448 just need to arrange for your build system to call
4449 `libltdl/configure' with appropriate options, and then run
4450 `make' in the `libltdl' subdirectory.
4452 If you _are_ using Autoconf and Automake, then you will need
4453 to add the following to your `configure.ac':
4455 LT_CONFIG_LTDL_DIR([libltdl])
4458 and to `Makefile.am':
4462 Aside from setting the libltdl build mode, there are other keywords
4463 that you can pass to `LTDL_INIT' to modify its behavior when
4464 `--with-included-ltdl' has been given:
4467 This is the default unless you explicitly add `installable' to
4468 your `LTDL_INIT' options.
4470 This keyword will cause options to be passed to the
4471 `configure' script in the subdirectory named by
4472 `LT_CONFIG_LTDL_DIR' in order to cause it to be built as a
4473 convenience library. If you're not using automake, you will
4474 need to define `top_build_prefix', `top_builddir', and
4475 `top_srcdir' in your makefile so that `LIBLTDL', `LTDLDEPS',
4476 and `LTDLINCL' expand correctly.
4478 One advantage of the convenience library is that it is not
4479 installed, so the fact that you use `libltdl' will not be
4480 apparent to the user, and it won't overwrite a pre-installed
4481 version of `libltdl' the system might already have in the
4482 installation directory. On the other hand, if you want to
4483 upgrade `libltdl' for any reason (e.g. a bugfix) you'll have
4484 to recompile your package instead of just replacing the
4485 shared installed version of `libltdl'. However, if your
4486 programs or libraries are linked with other libraries that
4487 use such a pre-installed version of `libltdl', you may get
4488 linker errors or run-time crashes. Another problem is that
4489 you cannot link the convenience library into more than one
4490 libtool library, then link a single program with those
4491 libraries, because you may get duplicate symbols. In general
4492 you can safely use the convenience library in programs that
4493 don't depend on other libraries that might use `libltdl' too.
4496 This keyword will pass options to the `configure' script in
4497 the subdirectory named by `LT_CONFIG_LTDL_DIR' in order to
4498 cause it to be built as an installable library. If you're not
4499 using automake, you will need to define `top_build_prefix',
4500 `top_builddir' and `top_srcdir' in your makefile so that
4501 `LIBLTDL', `LTDLDEPS', and `LTDLINCL' are expanded properly.
4503 Be aware that you could overwrite another `libltdl' already
4504 installed to the same directory if you use this option.
4506 Whatever method you use, `LTDL_INIT' will define the shell variable
4507 `LIBLTDL' to the link flag that you should use to link with `libltdl',
4508 the shell variable `LTDLDEPS' to the files that can be used as a
4509 dependency in `Makefile' rules, and the shell variable `LTDLINCL' to
4510 the preprocessor flag that you should use to compile programs that
4511 include `ltdl.h'. So, when you want to link a program with libltdl, be
4512 it a convenience, installed or installable library, just use
4513 `$(LTDLINCL)' for preprocessing and compilation, and `$(LIBLTDL)' for
4516 * If your package is built using an installed version of `libltdl',
4517 `LIBLTDL' will be set to the compiler flags needed to link against
4518 the installed library, `LTDLDEPS' will be empty, and `LTDLINCL'
4519 will be set to the compiler flags needed to find the `libltdl'
4522 * If your package is built using the convenience libltdl, `LIBLTDL'
4523 and `LTDLDEPS' will be the pathname for the convenience version of
4524 libltdl (starting with `${top_builddir}/' or
4525 `${top_build_prefix}') and `LTDLINCL' will be `-I' followed by the
4526 directory that contains `ltdl.h' (starting with `${top_srcdir}/').
4528 * If an installable version of the included `libltdl' is being
4529 built, its pathname starting with `${top_builddir}/' or
4530 `${top_build_prefix}', will be stored in `LIBLTDL' and `LTDLDEPS',
4531 and `LTDLINCL' will be set just like in the case of convenience
4534 You should probably also use the `dlopen' option to `LT_INIT' in
4535 your `configure.ac', otherwise libtool will assume no dlopening
4536 mechanism is supported, and revert to dlpreopening, which is probably
4537 not what you want. Avoid using the `-static', `-static-libtool-libs',
4538 or `-all-static' switches when linking programs with libltdl. This
4539 will not work on all platforms, because the dlopening functions may not
4540 be available for static linking.
4542 The following example shows you how to embed an installable libltdl
4543 in your package. In order to use the convenience variant, just replace
4544 the `LTDL_INIT' option `installable' with `convenience'. We assume
4545 that libltdl was embedded using `libtoolize --ltdl'.
4549 # Name the subdirectory that contains libltdl sources
4550 LT_CONFIG_LTDL_DIR([libltdl])
4552 # Configure libtool with dlopen support if possible
4555 # Enable building of the installable libltdl library
4556 LTDL_INIT([installable])
4563 AM_CPPFLAGS = $(LTDLINCL)
4565 myprog_LDFLAGS = -export-dynamic
4566 myprog_LDADD = $(LIBLTDL) -dlopen self -dlopen foo1.la
4567 myprog_DEPENDENCIES = $(LTDLDEPS) foo1.la
4570 -- Macro: LTDL_INSTALLABLE
4571 -- Macro: AC_LIBLTDL_INSTALLABLE
4572 These macros are deprecated, the `installable' option to
4573 `LTDL_INIT' should be used instead.
4575 -- Macro: LTDL_CONVENIENCE
4576 -- Macro: AC_LIBLTDL_CONVENIENCE
4577 These macros are deprecated, the `convenience' option to
4578 `LTDL_INIT' should be used instead.
4580 ---------- Footnotes ----------
4582 (1) We used to recommend adding the contents of `ltdl.m4' to
4583 `acinclude.m4', but with `aclocal' from a modern Automake (1.8 or
4584 newer) and this release of libltdl that is not only unnecessary but
4585 makes it easy to forget to upgrade `acinclude.m4' if you move to a
4586 different release of libltdl.
4588 (2) Even if libltdl is installed, `LTDL_INIT' may fail to detect it
4589 if libltdl depends on symbols provided by libraries other than the C
4593 File: libtool.info, Node: Trace interface, Next: FAQ, Prev: Using libltdl, Up: Top
4595 12 Libtool's trace interface
4596 ****************************
4598 This section describes macros whose sole purpose is to be traced using
4599 Autoconf's `--trace' option (*note The Autoconf Manual:
4600 (autoconf)autoconf Invocation.) to query the Libtool configuration of a
4601 project. These macros are called by Libtool internals and should never
4602 be called by user code; they should only be traced.
4604 -- Macro: LT_SUPPORTED_TAG (TAG)
4605 This macro is called once for each language enabled in the
4606 package. Its only argument, TAG, is the tag-name corresponding to
4607 the language (*note Tags::).
4609 You can therefore retrieve the list of all tags enabled in a
4610 project using the following command:
4611 autoconf --trace 'LT_SUPPORTED_TAG:$1'
4614 File: libtool.info, Node: FAQ, Next: Troubleshooting, Prev: Trace interface, Up: Top
4616 13 Frequently Asked Questions about libtool
4617 *******************************************
4619 This chapter covers some questions that often come up on the mailing
4624 * Stripped link flags:: Dropped flags when creating a library
4627 File: libtool.info, Node: Stripped link flags, Up: FAQ
4629 13.1 Why does libtool strip link flags when creating a library?
4630 ===============================================================
4632 When creating a shared library, but not when compiling or creating a
4633 program, `libtool' drops some flags from the command line provided by
4634 the user. This is done because flags unknown to `libtool' may
4635 interfere with library creation or require additional support from
4636 `libtool', and because omitting flags is usually the conservative
4637 choice for a successful build.
4639 If you encounter flags that you think are useful to pass, as a
4640 work-around you can prepend flags with `-Wc,' or `-Xcompiler ' to allow
4641 them to be passed through to the compiler driver (*note Link mode::).
4642 Another possibility is to add flags already to the compiler command at
4643 `configure' run time:
4645 ./configure CC='gcc -m64'
4647 If you think `libtool' should let some flag through by default,
4648 here's how you can test such an inclusion: grab the Libtool development
4649 tree, edit the `ltmain.m4sh' file in the `libltdl/config' subdirectory
4650 to pass through the flag (search for `Flags to be passed through'),
4651 re-bootstrap and build with the flags in question added to `LDFLAGS',
4652 `CFLAGS', `CXXFLAGS', etc. on the `configure' command line as
4653 appropriate. Run the testsuite as described in the `README' file and
4654 report results to the Libtool bug reporting address
4655 <bug-libtool@gnu.org>.
4658 File: libtool.info, Node: Troubleshooting, Next: Maintaining, Prev: FAQ, Up: Top
4663 Libtool is under constant development, changing to remain up-to-date
4664 with modern operating systems. If libtool doesn't work the way you
4665 think it should on your platform, you should read this chapter to help
4666 determine what the problem is, and how to resolve it.
4670 * Libtool test suite:: Libtool's self-tests.
4671 * Reporting bugs:: How to report problems with libtool.
4674 File: libtool.info, Node: Libtool test suite, Next: Reporting bugs, Up: Troubleshooting
4676 14.1 The libtool test suite
4677 ===========================
4679 Libtool comes with two integrated sets of tests to check that your build
4680 is sane, that test its capabilities, and report obvious bugs in the
4681 libtool program. These tests, too, are constantly evolving, based on
4682 past problems with libtool, and known deficiencies in other operating
4685 As described in the `README' file, you may run `make -k check' after
4686 you have built libtool (possibly before you install it) in order to
4687 make sure that it meets basic functional requirements.
4691 * Test descriptions:: The contents of the old test suite.
4692 * When tests fail:: What to do when a test fails.
4695 File: libtool.info, Node: Test descriptions, Next: When tests fail, Up: Libtool test suite
4697 14.1.1 Description of test suite
4698 --------------------------------
4700 Here is a list of the current programs in the old test suite, and what
4707 `cdemo-static-make.test'
4708 `cdemo-static-exec.test'
4710 `cdemo-shared-make.test'
4711 `cdemo-shared-exec.test'
4713 `cdemo-undef-make.test'
4714 `cdemo-undef-exec.test'
4715 These programs check to see that the `tests/cdemo' subdirectory of
4716 the libtool distribution can be configured and built correctly.
4718 The `tests/cdemo' subdirectory contains a demonstration of libtool
4719 convenience libraries, a mechanism that allows build-time static
4720 libraries to be created, in a way that their components can be
4721 later linked into programs or other libraries, even shared ones.
4723 The tests matching `cdemo-*make.test' and `cdemo-*exec.test' are
4724 executed three times, under three different libtool configurations:
4725 `cdemo-conf.test' configures `cdemo/libtool' to build both static
4726 and shared libraries (the default for platforms that support
4727 both), `cdemo-static.test' builds only static libraries
4728 (`--disable-shared'), and `cdemo-shared.test' builds only shared
4729 libraries (`--disable-static').
4731 The test `cdemo-undef.test' tests the generation of shared
4732 libraries with undefined symbols on systems that allow this.
4740 `demo-static-make.test'
4741 `demo-static-exec.test'
4742 `demo-static-inst.test'
4743 `demo-static-unst.test'
4745 `demo-shared-make.test'
4746 `demo-shared-exec.test'
4747 `demo-shared-inst.test'
4748 `demo-shared-unst.test'
4750 `demo-nofast-make.test'
4751 `demo-nofast-exec.test'
4752 `demo-nofast-inst.test'
4753 `demo-nofast-unst.test'
4755 `demo-pic-make.test'
4756 `demo-pic-exec.test'
4758 `demo-nopic-make.test'
4759 `demo-nopic-exec.test'
4760 These programs check to see that the `tests/demo' subdirectory of
4761 the libtool distribution can be configured, built, installed, and
4762 uninstalled correctly.
4764 The `tests/demo' subdirectory contains a demonstration of a trivial
4765 package that uses libtool. The tests matching `demo-*make.test',
4766 `demo-*exec.test', `demo-*inst.test' and `demo-*unst.test' are
4767 executed four times, under four different libtool configurations:
4768 `demo-conf.test' configures `demo/libtool' to build both static
4769 and shared libraries, `demo-static.test' builds only static
4770 libraries (`--disable-shared'), and `demo-shared.test' builds only
4771 shared libraries (`--disable-static'). `demo-nofast.test'
4772 configures `demo/libtool' to disable the fast-install mode
4773 (`--enable-fast-install=no'). `demo-pic.test' configures
4774 `demo/libtool' to prefer building PIC code (`--with-pic'),
4775 `demo-nopic.test' to prefer non-PIC code (`--without-pic').
4778 Many systems cannot link static libraries into shared libraries.
4779 libtool uses a `deplibs_check_method' to prevent such cases. This
4780 tests checks whether libtool's `deplibs_check_method' works
4783 `demo-hardcode.test'
4784 On all systems with shared libraries, the location of the library
4785 can be encoded in executables that are linked against it *note
4786 Linking executables::. This test checks the conditions under
4787 which your system linker hardcodes the library location, and
4788 guarantees that they correspond to libtool's own notion of how
4789 your linker behaves.
4792 `depdemo-relink.test'
4793 These tests check whether variable `shlibpath_overrides_runpath' is
4794 properly set. If the test fails, it will indicate what the
4795 variable should have been set to.
4797 `demo-noinst-link.test'
4798 Checks whether libtool will not try to link with a previously
4799 installed version of a library when it should be linking with a
4807 `depdemo-static.test'
4808 `depdemo-static-make.test'
4809 `depdemo-static-exec.test'
4810 `depdemo-static-inst.test'
4811 `depdemo-static-unst.test'
4812 `depdemo-shared.test'
4813 `depdemo-shared-make.test'
4814 `depdemo-shared-exec.test'
4815 `depdemo-shared-inst.test'
4816 `depdemo-shared-unst.test'
4817 `depdemo-nofast.test'
4818 `depdemo-nofast-make.test'
4819 `depdemo-nofast-exec.test'
4820 `depdemo-nofast-inst.test'
4821 `depdemo-nofast-unst.test'
4822 These programs check to see that the `tests/depdemo' subdirectory
4823 of the libtool distribution can be configured, built, installed,
4824 and uninstalled correctly.
4826 The `tests/depdemo' subdirectory contains a demonstration of
4827 inter-library dependencies with libtool. The test programs link
4828 some interdependent libraries.
4830 The tests matching `depdemo-*make.test', `depdemo-*exec.test',
4831 `depdemo-*inst.test' and `depdemo-*unst.test' are executed four
4832 times, under four different libtool configurations:
4833 `depdemo-conf.test' configures `depdemo/libtool' to build both
4834 static and shared libraries, `depdemo-static.test' builds only
4835 static libraries (`--disable-shared'), and `depdemo-shared.test'
4836 builds only shared libraries (`--disable-static').
4837 `depdemo-nofast.test' configures `depdemo/libtool' to disable the
4838 fast-install mode (`--enable-fast-install=no').
4846 `mdemo-static-make.test'
4847 `mdemo-static-exec.test'
4848 `mdemo-static-inst.test'
4849 `mdemo-static-unst.test'
4851 `mdemo-shared-make.test'
4852 `mdemo-shared-exec.test'
4853 `mdemo-shared-inst.test'
4854 `mdemo-shared-unst.test'
4855 These programs check to see that the `tests/mdemo' subdirectory of
4856 the libtool distribution can be configured, built, installed, and
4857 uninstalled correctly.
4859 The `tests/mdemo' subdirectory contains a demonstration of a
4860 package that uses libtool and the system independent dlopen wrapper
4861 `libltdl' to load modules. The library `libltdl' provides a
4862 dlopen wrapper for various platforms (POSIX) including support for
4863 dlpreopened modules (*note Dlpreopening::).
4865 The tests matching `mdemo-*make.test', `mdemo-*exec.test',
4866 `mdemo-*inst.test' and `mdemo-*unst.test' are executed three
4867 times, under three different libtool configurations:
4868 `mdemo-conf.test' configures `mdemo/libtool' to build both static
4869 and shared libraries, `mdemo-static.test' builds only static
4870 libraries (`--disable-shared'), and `mdemo-shared.test' builds
4871 only shared libraries (`--disable-static').
4874 This test checks whether libtool's `--dry-run' mode works properly.
4879 These programs check to see that the `tests/mdemo2' subdirectory of
4880 the libtool distribution can be configured, built, and executed
4883 The `tests/mdemo2' directory contains a demonstration of a package
4884 that attempts to link with a library (from the `tests/mdemo'
4885 directory) that itself does dlopening of libtool modules.
4888 This test guarantees that linking directly against a non-libtool
4889 static library works properly.
4892 This test makes sure that files ending in `.lo' are never linked
4893 directly into a program file.
4896 Check whether we can actually get help for libtool.
4899 Check that a nonexistent objectlist file is properly detected.
4905 These programs check to see that the `tests/pdemo' subdirectory of
4906 the libtool distribution can be configured, built, and executed
4909 The `pdemo-conf.test' lowers the `max_cmd_len' variable in the
4910 generated libtool script to test the measures to evade command line
4914 This program checks libtool's metacharacter quoting.
4917 Checks for some nonportable or dubious or undesired shell
4918 constructs in shell scripts.
4921 When other programming languages are used with libtool (*note
4922 Other languages::), the source files may end in suffixes other
4923 than `.c'. This test validates that libtool can handle suffixes
4924 for all the file types that it supports, and that it fails when
4925 the suffix is invalid.
4930 `tagdemo-static.test'
4931 `tagdemo-static-make.test'
4932 `tagdemo-static-exec.test'
4933 `tagdemo-shared.test'
4934 `tagdemo-shared-make.test'
4935 `tagdemo-shared-exec.test'
4936 `tagdemo-undef.test'
4937 `tagdemo-undef-make.test'
4938 `tagdemo-undef-exec.test'
4939 These programs check to see that the `tests/tagdemo' subdirectory
4940 of the libtool distribution can be configured, built, and executed
4943 The `tests/tagdemo' directory contains a demonstration of a package
4944 that uses libtool's multi-language support through configuration
4945 tags. It generates a library from C++ sources, which is then
4946 linked to a C++ program.
4951 `f77demo-static.test'
4952 `f77demo-static-make.test'
4953 `f77demo-static-exec.test'
4954 `f77demo-shared.test'
4955 `f77demo-shared-make.test'
4956 `f77demo-shared-exec.test'
4957 These programs check to see that the `tests/f77demo' subdirectory
4958 of the libtool distribution can be configured, built, and executed
4961 The `tests/f77demo' tests test Fortran 77 support in libtool by
4962 creating libraries from Fortran 77 sources, and mixed Fortran and C
4963 sources, and a Fortran 77 program to use the former library, and a
4964 C program to use the latter library.
4969 `fcdemo-static.test'
4970 `fcdemo-static-make.test'
4971 `fcdemo-static-exec.test'
4972 `fcdemo-shared.test'
4973 `fcdemo-shared-make.test'
4974 `fcdemo-shared-exec.test'
4975 These programs check to see that the `tests/fcdemo' subdirectory
4976 of the libtool distribution can be configured, built, and executed
4979 The `tests/fcdemo' is similar to the `tests/f77demo' directory,
4980 except that Fortran 90 is used in combination with the `FC'
4981 interface provided by Autoconf and Automake.
4984 The new, Autotest-based test suite uses keywords to classify certain
4991 The test group exercises one of these `libtool' language tags.
4995 These keywords denote that the respective external program is
4996 needed by the test group. The tests are typically skipped if the
4997 program is not installed. The `automake' keyword may also denote
4998 use of the `aclocal' program.
5001 This test group may require user interaction on some systems.
5002 Typically, this means closing a popup window about a DLL load
5006 Denote that the `libltdl' library is exercised by the test group.
5010 Denote that the `libtool' or `libtoolize' scripts are exercised by
5011 the test group, respectively.
5014 Denote that this test group may recursively re-invoke the test
5015 suite itself, with changed settings and maybe a changed `libtool'
5016 script. You may use the `INNER_TESTSUITEFLAGS' variable to pass
5017 additional settings to this recursive invocation. Typically,
5018 recursive invocations delimit the set of tests with another
5019 keyword, for example by passing `-k libtool' right before the
5020 expansion of the `INNER_TESTSUITEFLAGS' variable (without an
5021 intervening space, so you get the chance for further delimitation).
5023 Test groups with the keyword `recursive' should not be denoted with
5024 keywords, in order to avoid infinite recursion. As a consequence,
5025 recursive test groups themselves should never require user
5026 interaction, while the test groups they invoke may do so.
5028 There is a convenience target `check-noninteractive' that runs all
5029 tests from both test suites that do not cause user interaction on
5030 Windows. Conversely, the target `check-interactive' runs the
5031 complement of tests and might require closing popup windows about DLL
5032 load errors on Windows.
5035 File: libtool.info, Node: When tests fail, Prev: Test descriptions, Up: Libtool test suite
5037 14.1.2 When tests fail
5038 ----------------------
5040 When the tests in the old test suite are run via `make check', output
5041 is caught in per-test `tests/TEST-NAME.log' files and summarized in the
5042 `test-suite.log' file. The exit status of each program tells the
5043 `Makefile' whether or not the test succeeded.
5045 If a test fails, it means that there is either a programming error in
5046 libtool, or in the test program itself.
5048 To investigate a particular test, you may run it directly, as you
5049 would a normal program. When the test is invoked in this way, it
5050 produces output that may be useful in determining what the problem is.
5052 The new, Autotest-based test suite produces as output a file
5053 `tests/testsuite.log' which contains information about failed tests.
5055 You can pass options to the test suite through the `make' variable
5056 `TESTSUITEFLAGS' (*note The Autoconf Manual: (autoconf)testsuite
5060 File: libtool.info, Node: Reporting bugs, Prev: Libtool test suite, Up: Troubleshooting
5065 If you think you have discovered a bug in libtool, you should think
5066 twice: the libtool maintainer is notorious for passing the buck (or
5067 maybe that should be "passing the bug"). Libtool was invented to fix
5068 known deficiencies in shared library implementations, so, in a way, most
5069 of the bugs in libtool are actually bugs in other operating systems.
5070 However, the libtool maintainer would definitely be happy to add support
5071 for somebody else's buggy operating system. [I wish there was a good
5072 way to do winking smiley-faces in Texinfo.]
5074 Genuine bugs in libtool include problems with shell script
5075 portability, documentation errors, and failures in the test suite
5076 (*note Libtool test suite::).
5078 First, check the documentation and help screens to make sure that the
5079 behaviour you think is a problem is not already mentioned as a feature.
5081 Then, you should read the Emacs guide to reporting bugs (*note
5082 Reporting Bugs: (emacs)Bugs.). Some of the details listed there are
5083 specific to Emacs, but the principle behind them is a general one.
5085 Finally, send a bug report to the Libtool bug reporting address
5086 <bug-libtool@gnu.org> with any appropriate _facts_, such as test suite
5087 output (*note When tests fail::), all the details needed to reproduce
5088 the bug, and a brief description of why you think the behaviour is a
5089 bug. Be sure to include the word "libtool" in the subject line, as
5090 well as the version number you are using (which can be found by typing
5091 `libtool --version').
5094 File: libtool.info, Node: Maintaining, Next: GNU Free Documentation License, Prev: Troubleshooting, Up: Top
5096 15 Maintenance notes for libtool
5097 ********************************
5099 This chapter contains information that the libtool maintainer finds
5100 important. It will be of no use to you unless you are considering
5101 porting libtool to new systems, or writing your own libtool.
5105 * New ports:: How to port libtool to new systems.
5106 * Tested platforms:: When libtool was last tested.
5107 * Platform quirks:: Information about different library systems.
5108 * libtool script contents:: Configuration information that libtool uses.
5109 * Cheap tricks:: Making libtool maintainership easier.
5112 File: libtool.info, Node: New ports, Next: Tested platforms, Up: Maintaining
5114 15.1 Porting libtool to new systems
5115 ===================================
5117 Before you embark on porting libtool to an unsupported system, it is
5118 worthwhile to send e-mail to the Libtool mailing list
5119 <libtool@gnu.org>, to make sure that you are not duplicating existing
5122 If you find that any porting documentation is missing, please
5123 complain! Complaints with patches and improvements to the
5124 documentation, or to libtool itself, are more than welcome.
5128 * Information sources:: Where to find relevant documentation
5129 * Porting inter-library dependencies:: Implementation details explained
5132 File: libtool.info, Node: Information sources, Next: Porting inter-library dependencies, Up: New ports
5134 15.1.1 Information sources
5135 --------------------------
5137 Once it is clear that a new port is necessary, you'll generally need the
5138 following information:
5140 canonical system name
5141 You need the output of `config.guess' for this system, so that you
5142 can make changes to the libtool configuration process without
5143 affecting other systems.
5145 man pages for `ld' and `cc'
5146 These generally describe what flags are used to generate PIC, to
5147 create shared libraries, and to link against only static
5148 libraries. You may need to follow some cross references to find
5149 the information that is required.
5151 man pages for `ld.so', `rtld', or equivalent
5152 These are a valuable resource for understanding how shared
5153 libraries are loaded on the system.
5155 man page for `ldconfig', or equivalent
5156 This page usually describes how to install shared libraries.
5158 output from `ls -l /lib /usr/lib'
5159 This shows the naming convention for shared libraries on the
5160 system, including which names should be symbolic links.
5162 any additional documentation
5163 Some systems have special documentation on how to build and install
5166 If you know how to program the Bourne shell, then you can complete
5167 the port yourself; otherwise, you'll have to find somebody with the
5168 relevant skills who will do the work. People on the libtool mailing
5169 list are usually willing to volunteer to help you with new ports, so
5170 you can send the information to them.
5172 To do the port yourself, you'll definitely need to modify the
5173 `libtool.m4' macros in order to make platform-specific changes to the
5174 configuration process. You should search that file for the `PORTME'
5175 keyword, which will give you some hints on what you'll need to change.
5176 In general, all that is involved is modifying the appropriate
5177 configuration variables (*note libtool script contents::).
5179 Your best bet is to find an already-supported system that is similar
5180 to yours, and make your changes based on that. In some cases, however,
5181 your system will differ significantly from every other supported system,
5182 and it may be necessary to add new configuration variables, and modify
5183 the `ltmain.in' script accordingly. Be sure to write to the mailing
5184 list before you make changes to `ltmain.in', since they may have advice
5185 on the most effective way of accomplishing what you want.
5188 File: libtool.info, Node: Porting inter-library dependencies, Prev: Information sources, Up: New ports
5190 15.1.2 Porting inter-library dependencies support
5191 -------------------------------------------------
5193 Since version 1.2c, libtool has re-introduced the ability to do
5194 inter-library dependency on some platforms, thanks to a patch by Toshio
5195 Kuratomi <badger@prtr-13.ucsc.edu>. Here's a shortened version of the
5196 message that contained his patch:
5198 The basic architecture is this: in `libtool.m4', the person who
5199 writes libtool makes sure `$deplibs' is included in `$archive_cmds'
5200 somewhere and also sets the variable `$deplibs_check_method', and maybe
5201 `$file_magic_cmd' when `deplibs_check_method' is file_magic.
5203 `deplibs_check_method' can be one of five things:
5204 `file_magic [REGEX]'
5205 looks in the library link path for libraries that have the right
5206 libname. Then it runs `$file_magic_cmd' on the library and checks
5207 for a match against the extended regular expression REGEX. When
5208 `file_magic_test_file' is set by `libtool.m4', it is used as an
5209 argument to `$file_magic_cmd' in order to verify whether the
5210 regular expression matches its output, and warn the user otherwise.
5213 just checks whether it is possible to link a program out of a list
5214 of libraries, and checks which of those are listed in the output of
5215 `ldd'. It is currently unused, and will probably be dropped in the
5219 will pass everything without any checking. This may work on
5220 platforms in which code is position-independent by default and
5221 inter-library dependencies are properly supported by the dynamic
5222 linker, for example, on DEC OSF/1 3 and 4.
5225 It causes deplibs to be reassigned `deplibs=""'. That way
5226 `archive_cmds' can contain deplibs on all platforms, but not have
5227 deplibs used unless needed.
5230 is the default for all systems unless overridden in `libtool.m4'.
5231 It is the same as `none', but it documents that we really don't
5232 know what the correct value should be, and we welcome patches that
5235 Then in `ltmain.in' we have the real workhorse: a little
5236 initialization and postprocessing (to setup/release variables for use
5237 with eval echo libname_spec etc.) and a case statement that decides the
5238 method that is being used. This is the real code... I wish I could
5239 condense it a little more, but I don't think I can without function
5240 calls. I've mostly optimized it (moved things out of loops, etc.) but
5241 there is probably some fat left. I thought I should stop while I was
5242 ahead, work on whatever bugs you discover, etc. before thinking about
5243 more than obvious optimizations.
5246 File: libtool.info, Node: Tested platforms, Next: Platform quirks, Prev: New ports, Up: Maintaining
5248 15.2 Tested platforms
5249 =====================
5251 This table describes when libtool was last known to be tested on
5252 platforms where it claims to support shared libraries:
5254 -------------------------------------------------------
5255 canonical host name compiler libtool results
5256 (tools versions) release
5257 -------------------------------------------------------
5258 alpha-dec-osf5.1 cc 1.3e ok (1.910)
5259 alpha-dec-osf4.0f gcc 1.3e ok (1.910)
5260 alpha-dec-osf4.0f cc 1.3e ok (1.910)
5261 alpha-dec-osf3.2 gcc 0.8 ok
5262 alpha-dec-osf3.2 cc 0.8 ok
5263 alpha-dec-osf2.1 gcc 1.2f NS
5264 alpha*-unknown-linux-gnu gcc 1.3b ok
5265 (egcs-1.1.2, GNU ld 2.9.1.0.23)
5266 hppa2.0w-hp-hpux11.00 cc 1.2f ok
5267 hppa2.0-hp-hpux10.20 cc 1.3.2 ok
5268 hppa1.1-hp-hpux10.20 gcc 1.2f ok
5269 hppa1.1-hp-hpux10.20 cc 1.3c ok (1.821)
5270 hppa1.1-hp-hpux10.10 gcc 1.2f ok
5271 hppa1.1-hp-hpux10.10 cc 1.2f ok
5272 hppa1.1-hp-hpux9.07 gcc 1.2f ok
5273 hppa1.1-hp-hpux9.07 cc 1.2f ok
5274 hppa1.1-hp-hpux9.05 gcc 1.2f ok
5275 hppa1.1-hp-hpux9.05 cc 1.2f ok
5276 hppa1.1-hp-hpux9.01 gcc 1.2f ok
5277 hppa1.1-hp-hpux9.01 cc 1.2f ok
5278 i*86-*-beos gcc 1.2f ok
5279 i*86-*-bsdi4.0.1 gcc 1.3c ok
5281 i*86-*-bsdi4.0 gcc 1.2f ok
5282 i*86-*-bsdi3.1 gcc 1.2e NS
5283 i*86-*-bsdi3.0 gcc 1.2e NS
5284 i*86-*-bsdi2.1 gcc 1.2e NS
5285 i*86-pc-cygwin gcc 1.3b NS
5286 (egcs-1.1 stock b20.1 compiler)
5287 i*86-*-dguxR4.20MU01 gcc 1.2 ok
5288 i*86-*-freebsd4.3 gcc 1.3e ok (1.912)
5289 i*86-*-freebsdelf4.0 gcc 1.3c ok
5291 i*86-*-freebsdelf3.2 gcc 1.3c ok
5293 i*86-*-freebsdelf3.1 gcc 1.3c ok
5295 i*86-*-freebsdelf3.0 gcc 1.3c ok
5296 i*86-*-freebsd3.0 gcc 1.2e ok
5297 i*86-*-freebsd2.2.8 gcc 1.3c ok
5299 i*86-*-freebsd2.2.6 gcc 1.3b ok
5300 (egcs-1.1 & gcc-2.7.2.1, native ld)
5301 i*86-*-freebsd2.1.5 gcc 0.5 ok
5302 i*86-*-netbsd1.5 gcc 1.3e ok (1.901)
5304 i*86-*-netbsd1.4 gcc 1.3c ok
5306 i*86-*-netbsd1.4.3A gcc 1.3e ok (1.901)
5307 i*86-*-netbsd1.3.3 gcc 1.3c ok
5309 i*86-*-netbsd1.3.2 gcc 1.2e ok
5310 i*86-*-netbsd1.3I gcc 1.2e ok
5312 i*86-*-netbsd1.2 gcc 0.9g ok
5313 i*86-*-linux-gnu gcc 1.3e ok (1.901)
5314 (Red Hat 7.0, gcc "2.96")
5315 i*86-*-linux-gnu gcc 1.3e ok (1.911)
5316 (SuSE 7.0, gcc 2.95.2)
5317 i*86-*-linux-gnulibc1 gcc 1.2f ok
5318 i*86-*-openbsd2.5 gcc 1.3c ok
5320 i*86-*-openbsd2.4 gcc 1.3c ok
5322 i*86-*-solaris2.7 gcc 1.3b ok
5323 (egcs-1.1.2, native ld)
5324 i*86-*-solaris2.6 gcc 1.2f ok
5325 i*86-*-solaris2.5.1 gcc 1.2f ok
5326 i*86-ncr-sysv4.3.03 gcc 1.2f ok
5327 i*86-ncr-sysv4.3.03 cc 1.2e ok
5329 i*86-pc-sco3.2v5.0.5 cc 1.3c ok
5330 i*86-pc-sco3.2v5.0.5 gcc 1.3c ok
5332 i*86-pc-sco3.2v5.0.5 gcc 1.3c ok
5334 i*86-sco-sysv5uw7.1.1 gcc 1.3e ok (1.901)
5335 (gcc-2.95.2, SCO linker)
5336 i*86-UnixWare7.1.0-sysv5 cc 1.3c ok
5337 i*86-UnixWare7.1.0-sysv5 gcc 1.3c ok
5339 m68k-next-nextstep3 gcc 1.2f NS
5340 m68k-sun-sunos4.1.1 gcc 1.2f NS
5342 m88k-dg-dguxR4.12TMU01 gcc 1.2 ok
5343 m88k-motorola-sysv4 gcc 1.3 ok
5345 mips-sgi-irix6.5 gcc 1.2f ok
5347 mips-sgi-irix6.4 gcc 1.2f ok
5348 mips-sgi-irix6.3 gcc 1.3b ok
5349 (egcs-1.1.2, native ld)
5350 mips-sgi-irix6.3 cc 1.3b ok
5352 mips-sgi-irix6.2 gcc 1.2f ok
5353 mips-sgi-irix6.2 cc 0.9 ok
5354 mips-sgi-irix5.3 gcc 1.2f ok
5356 mips-sgi-irix5.3 gcc 1.2f NS
5358 mips-sgi-irix5.3 cc 0.8 ok
5359 mips-sgi-irix5.2 gcc 1.3b ok
5360 (egcs-1.1.2, native ld)
5361 mips-sgi-irix5.2 cc 1.3b ok
5363 mips-sni-sysv4 cc 1.3.5 ok
5364 (Siemens C-compiler)
5365 mips-sni-sysv4 gcc 1.3.5 ok
5366 (gcc-2.7.2.3, GNU assembler 2.8.1, native ld)
5367 mipsel-unknown-openbsd2.1 gcc 1.0 ok
5368 powerpc-apple-darwin6.4 gcc 1.5 ok
5369 (apple dev tools released 12/2002)
5370 powerpc-ibm-aix4.3.1.0 gcc 1.2f ok
5372 powerpc-ibm-aix4.2.1.0 gcc 1.2f ok
5374 powerpc-ibm-aix4.1.5.0 gcc 1.2f ok
5376 powerpc-ibm-aix4.1.5.0 gcc 1.2f NS
5378 powerpc-ibm-aix4.1.4.0 gcc 1.0 ok
5379 powerpc-ibm-aix4.1.4.0 xlc 1.0i ok
5380 rs6000-ibm-aix4.1.5.0 gcc 1.2f ok
5382 rs6000-ibm-aix4.1.4.0 gcc 1.2f ok
5384 rs6000-ibm-aix3.2.5 gcc 1.0i ok
5385 rs6000-ibm-aix3.2.5 xlc 1.0i ok
5386 sparc-sun-solaris2.8 gcc 1.3e ok (1.913)
5387 (gcc-2.95.3 & native ld)
5388 sparc-sun-solaris2.7 gcc 1.3e ok (1.913)
5389 (gcc-2.95.3 & native ld)
5390 sparc-sun-solaris2.6 gcc 1.3e ok (1.913)
5391 (gcc-2.95.3 & native ld)
5392 sparc-sun-solaris2.5.1 gcc 1.3e ok (1.911)
5393 sparc-sun-solaris2.5 gcc 1.3b ok
5394 (egcs-1.1.2, GNU ld 2.9.1 & native ld)
5395 sparc-sun-solaris2.5 cc 1.3b ok
5397 sparc-sun-solaris2.4 gcc 1.0a ok
5398 sparc-sun-solaris2.4 cc 1.0a ok
5399 sparc-sun-solaris2.3 gcc 1.2f ok
5400 sparc-sun-sunos4.1.4 gcc 1.2f ok
5401 sparc-sun-sunos4.1.4 cc 1.0f ok
5402 sparc-sun-sunos4.1.3_U1 gcc 1.2f ok
5403 sparc-sun-sunos4.1.3C gcc 1.2f ok
5404 sparc-sun-sunos4.1.3 gcc 1.3b ok
5405 (egcs-1.1.2, GNU ld 2.9.1 & native ld)
5406 sparc-sun-sunos4.1.3 cc 1.3b ok
5407 sparc-unknown-bsdi4.0 gcc 1.2c ok
5408 sparc-unknown-linux-gnulibc1 gcc 1.2f ok
5409 sparc-unknown-linux-gnu gcc 1.3b ok
5410 (egcs-1.1.2, GNU ld 2.9.1.0.23)
5411 sparc64-unknown-linux-gnu gcc 1.2f ok
5414 - "ok" means "all tests passed".
5415 - "NS" means "Not Shared", but OK for static libraries
5417 Note: The vendor-distributed HP-UX `sed'(1) programs are horribly
5418 broken, and cannot handle libtool's requirements, so users may report
5419 unusual problems. There is no workaround except to install a working
5420 `sed' (such as GNU `sed') on these systems.
5422 Note: The vendor-distributed NCR MP-RAS `cc' programs emits
5423 copyright on standard error that confuse tests on size of
5424 `conftest.err'. The workaround is to specify `CC' when run `configure'
5425 with `CC='cc -Hnocopyr''.
5428 File: libtool.info, Node: Platform quirks, Next: libtool script contents, Prev: Tested platforms, Up: Maintaining
5430 15.3 Platform quirks
5431 ====================
5433 This section is dedicated to the sanity of the libtool maintainers. It
5434 describes the programs that libtool uses, how they vary from system to
5435 system, and how to test for them.
5437 Because libtool is a shell script, it can be difficult to understand
5438 just by reading it from top to bottom. This section helps show why
5439 libtool does things a certain way. Combined with the scripts
5440 themselves, you should have a better sense of how to improve libtool, or
5445 * References:: Finding more information.
5446 * Compilers:: Creating object files from source files.
5447 * Reloadable objects:: Binding object files together.
5448 * Multiple dependencies:: Removing duplicate dependent libraries.
5449 * Archivers:: Programs that create static archives.
5450 * Cross compiling:: Issues that arise when cross compiling.
5451 * File name conversion:: Converting file names between platforms.
5452 * Windows DLLs:: Windows header defines.
5455 File: libtool.info, Node: References, Next: Compilers, Up: Platform quirks
5460 The following is a list of valuable documentation references:
5462 * SGI's IRIX Manual Pages can be found at
5463 `http://techpubs.sgi.com/cgi-bin/infosrch.cgi?cmd=browse&db=man'.
5465 * Sun's free service area
5466 (`http://www.sun.com/service/online/free.html') and documentation
5467 server (`http://docs.sun.com/').
5469 * Compaq's Tru64 UNIX online documentation is at
5470 (`http://tru64unix.compaq.com/faqs/publications/pub_page/doc_list.html')
5471 with C++ documentation at
5472 (`http://tru64unix.compaq.com/cplus/docs/index.htm').
5474 * Hewlett-Packard has online documentation at
5475 (`http://docs.hp.com/index.html').
5477 * IBM has online documentation at
5478 (`http://www.rs6000.ibm.com/resource/aix_resource/Pubs/').
5481 File: libtool.info, Node: Compilers, Next: Reloadable objects, Prev: References, Up: Platform quirks
5486 The only compiler characteristics that affect libtool are the flags
5487 needed (if any) to generate PIC objects. In general, if a C compiler
5488 supports certain PIC flags, then any derivative compilers support the
5489 same flags. Until there are some noteworthy exceptions to this rule,
5490 this section will document only C compilers.
5492 The following C compilers have standard command line options,
5493 regardless of the platform:
5496 This is the GNU C compiler, which is also the system compiler for
5497 many free operating systems (FreeBSD, GNU/Hurd, GNU/Linux, Lites,
5498 NetBSD, and OpenBSD, to name a few).
5500 The `-fpic' or `-fPIC' flags can be used to generate
5501 position-independent code. `-fPIC' is guaranteed to generate
5502 working code, but the code is slower on m68k, m88k, and Sparc
5503 chips. However, using `-fpic' on those chips imposes arbitrary
5504 size limits on the shared libraries.
5506 The rest of this subsection lists compilers by the operating system
5507 that they are bundled with:
5511 Most AIX compilers have no PIC flags, since AIX (with the
5512 exception of AIX for IA-64) runs on PowerPC and RS/6000 chips. (1)
5515 Use `+Z' to generate PIC.
5518 Digital/UNIX 3.x does not have PIC flags, at least not on the
5522 Use `-KPIC' to generate PIC.
5525 Use `-PIC' to generate PIC.
5527 ---------- Footnotes ----------
5529 (1) All code compiled for the PowerPC and RS/6000 chips
5530 (`powerpc-*-*', `powerpcle-*-*', and `rs6000-*-*') is
5531 position-independent, regardless of the operating system or compiler
5532 suite. So, "regular objects" can be used to build shared libraries on
5533 these systems and no special PIC compiler flags are required.
5536 File: libtool.info, Node: Reloadable objects, Next: Multiple dependencies, Prev: Compilers, Up: Platform quirks
5538 15.3.3 Reloadable objects
5539 -------------------------
5541 On all known systems, a reloadable object can be created by running `ld
5542 -r -o OUTPUT.o INPUT1.o INPUT2.o'. This reloadable object may be
5543 treated as exactly equivalent to other objects.
5546 File: libtool.info, Node: Multiple dependencies, Next: Archivers, Prev: Reloadable objects, Up: Platform quirks
5548 15.3.4 Multiple dependencies
5549 ----------------------------
5551 On most modern platforms the order in which dependent libraries are
5552 listed has no effect on object generation. In theory, there are
5553 platforms that require libraries that provide missing symbols to other
5554 libraries to be listed after those libraries whose symbols they provide.
5556 Particularly, if a pair of static archives each resolve some of the
5557 other's symbols, it might be necessary to list one of those archives
5558 both before and after the other one. Libtool does not currently cope
5559 with this situation well, since duplicate libraries are removed from
5560 the link line by default. Libtool provides the command line option
5561 `--preserve-dup-deps' to preserve all duplicate dependencies in cases
5562 where it is necessary.
5565 File: libtool.info, Node: Archivers, Next: Cross compiling, Prev: Multiple dependencies, Up: Platform quirks
5570 On all known systems, building a static library can be accomplished by
5571 running `ar cru libNAME.a OBJ1.o OBJ2.o ...', where the `.a' file is
5572 the output library, and each `.o' file is an object file.
5574 On all known systems, if there is a program named `ranlib', then it
5575 must be used to "bless" the created library before linking against it,
5576 with the `ranlib libNAME.a' command. Some systems, like Irix, use the
5577 `ar ts' command, instead.
5580 File: libtool.info, Node: Cross compiling, Next: File name conversion, Prev: Archivers, Up: Platform quirks
5582 15.3.6 Cross compiling
5583 ----------------------
5585 Most build systems support the ability to compile libraries and
5586 applications on one platform for use on a different platform, provided
5587 a compiler capable of generating the appropriate output is available.
5588 In such cross compiling scenarios, the platform on which the libraries
5589 or applications are compiled is called the "build platform", while the
5590 platform on which the libraries or applications are intended to be used
5591 or executed is called the "host platform". *note The GNU Build System:
5592 (automake)GNU Build System, of which libtool is a part, supports cross
5593 compiling via arguments passed to the configure script: `--build=...'
5594 and `--host=...'. However, when the build platform and host platform
5595 are very different, libtool is required to make certain accommodations
5596 to support these scenarios.
5598 In most cases, because the build platform and host platform differ,
5599 the cross-compiled libraries and executables can't be executed or
5600 tested on the build platform where they were compiled. The testsuites
5601 of most build systems will often skip any tests that involve executing
5602 such foreign executables when cross-compiling. However, if the build
5603 platform and host platform are sufficiently similar, it is often
5604 possible to run cross-compiled applications. Libtool's own testsuite
5605 often attempts to execute cross-compiled tests, but will mark any
5606 failures as _skipped_ since the failure might simply be due to the
5607 differences between the two platforms.
5609 In addition to cases where the host platform and build platform are
5610 extremely similar (e.g. `i586-pc-linux-gnu' and `i686-pc-linux-gnu'),
5611 there is another case in which cross-compiled host applications may be
5612 executed on the build platform. This is possible when the build
5613 platform supports an emulation or API-enhanced environment for the host
5614 platform. One example of this situation would be if the build platform
5615 were MinGW, and the host platform were Cygwin (or vice versa). Both of
5616 these platforms can actually operate within a single Windows instance,
5617 so Cygwin applications can be launched from a MinGW context, and vice
5618 versa--provided certain care is taken. Another example would be if the
5619 build platform were GNU/Linux on an x86 32bit processor, and the host
5620 platform were MinGW. In this situation, the Wine
5621 (http://www.winehq.org/) environment can be used to launch Windows
5622 applications from the GNU/Linux operating system; again, provided
5623 certain care is taken.
5625 One particular issue occurs when a Windows platform such as MinGW,
5626 Cygwin, or MSYS is the host or build platform, while the other platform
5627 is a Unix-style system. In these cases, there are often conflicts
5628 between the format of the file names and paths expected within host
5629 platform libraries and executables, and those employed on the build
5632 This situation is best described using a concrete example: suppose
5633 the build platform is GNU/Linux with canonical triplet
5634 `i686-pc-linux-gnu'. Suppose further that the host platform is MinGW
5635 with canonical triplet `i586-pc-mingw32'. On the GNU/Linux platform
5636 there is a cross compiler following the usual naming conventions of
5637 such compilers, where the compiler name is prefixed by the host
5638 canonical triplet (or suitable alias). (For more information
5639 concerning canonical triplets and platform aliases, see *note
5640 Specifying Target Triplets: (autoconf)Specifying Target Triplets. and
5641 *note Canonicalizing: (autoconf)Canonicalizing.) In this case, the C
5642 compiler is named `i586-pc-mingw32-gcc'.
5644 As described in *note Wrapper executables::, for the MinGW host
5645 platform libtool uses a wrapper executable to set various environment
5646 variables before launching the actual program executable. Like the
5647 program executable, the wrapper executable is cross-compiled for the
5648 host platform (that is, for MinGW). As described above, ordinarily a
5649 host platform executable cannot be executed on the build platform, but
5650 in this case the Wine environment could be used to launch the MinGW
5651 application from GNU/Linux. However, the wrapper executable, as a host
5652 platform (MinGW) application, must set the `PATH' variable so that the
5653 true application's dependent libraries can be located--but the contents
5654 of the `PATH' variable must be structured for MinGW. Libtool must use
5655 the Wine file name mapping facilities to determine the correct value so
5656 that the wrapper executable can set the `PATH' variable to point to the
5659 For example, suppose we are compiling an application in `/var/tmp' on
5660 GNU/Linux, using separate source code and build directories:
5662 `/var/tmp/foo-1.2.3/app/' (application source code)
5663 `/var/tmp/foo-1.2.3/lib/' (library source code)
5664 `/var/tmp/BUILD/app/' (application build objects here)
5665 `/var/tmp/BUILD/lib/' (library build objects here)
5667 Since the library will be built in `/var/tmp/BUILD/lib', the wrapper
5668 executable (which will be in `/var/tmp/BUILD/app') must add that
5669 directory to `PATH' (actually, it must add the directory named OBJDIR
5670 under `/var/tmp/BUILD/lib', but we'll ignore that detail for now).
5671 However, Windows does not have a concept of Unix-style file or
5672 directory names such as `/var/tmp/BUILD/lib'. Therefore, Wine provides
5673 a mapping from Windows file names such as `C:\Program Files' to specific
5674 Unix-style file names. Wine also provides a utility that can be used
5675 to map Unix-style file names to Windows file names.
5677 In this case, the wrapper executable should actually add the value
5679 Z:\var\tmp\BUILD\lib
5681 to the `PATH'. libtool contains support for path conversions of this
5682 type, for a certain limited set of build and host platform
5683 combinations. In this case, libtool will invoke Wine's `winepath'
5684 utility to ensure that the correct `PATH' value is used. For more
5685 information, see *note File name conversion::.
5688 File: libtool.info, Node: File name conversion, Next: Windows DLLs, Prev: Cross compiling, Up: Platform quirks
5690 15.3.7 File name conversion
5691 ---------------------------
5693 In certain situations, libtool must convert file names and paths between
5694 formats appropriate to different platforms. Usually this occurs when
5695 cross-compiling, and affects only the ability to launch host platform
5696 executables on the build platform using an emulation or API-enhancement
5697 environment such as Wine. Failure to convert paths (*note File Name
5698 Conversion Failure::) will cause a warning to be issued, but rarely
5699 causes the build to fail--and should have no affect on the compiled
5700 products, once installed properly on the host platform. For more
5701 information, *note Cross compiling::.
5703 However, file name conversion may also occur in another scenario:
5704 when using a Unix emulation system on Windows (such as Cygwin or MSYS),
5705 combined with a native Windows compiler such as MinGW or MSVC. Only a
5706 limited set of such scenarios are currently supported; in other cases
5707 file name conversion is skipped. The lack of file name conversion
5708 usually means that uninstalled executables can't be launched, but only
5709 rarely causes the build to fail (*note File Name Conversion Failure::).
5711 libtool supports file name conversion in the following scenarios:
5713 build platform host platform Notes
5714 ---------------------------------------------------------------------------
5715 MinGW (MSYS) MinGW (Windows) *note Native MinGW File Name
5717 Cygwin MinGW (Windows) *note Cygwin/Windows File Name
5719 Unix + Wine MinGW (Windows) Requires Wine. *note Unix/Windows
5720 File Name Conversion::
5721 MinGW (MSYS) Cygwin Requires `LT_CYGPATH'. *note
5722 LT_CYGPATH::. Provided for testing
5724 Unix + Wine Cygwin Requires both Wine and
5725 `LT_CYGPATH', but does not yet work
5726 with Cygwin 1.7.7 and Wine-1.2.
5727 See *note Unix/Windows File Name
5728 Conversion:: and *note LT_CYGPATH::.
5732 * File Name Conversion Failure:: What happens when file name conversion fails
5733 * Native MinGW File Name Conversion:: MSYS file name conversion idiosyncrasies
5734 * Cygwin/Windows File Name Conversion:: Using `cygpath' to convert Cygwin file names
5735 * Unix/Windows File Name Conversion:: Using Wine to convert Unix paths
5736 * LT_CYGPATH:: Invoking `cygpath' from other environments
5737 * Cygwin to MinGW Cross:: Other notes concerning MinGW cross
5740 File: libtool.info, Node: File Name Conversion Failure, Next: Native MinGW File Name Conversion, Up: File name conversion
5742 15.3.7.1 File Name Conversion Failure
5743 .....................................
5745 In most cases, file name conversion is not needed or attempted.
5746 However, when libtool detects that a specific combination of build and
5747 host platform does require file name conversion, it is possible that
5748 the conversion may fail. In these cases, you may see a warning such as
5751 Could not determine the host file name corresponding to
5752 `... a file name ...'
5753 Continuing, but uninstalled executables may not work.
5757 Could not determine the host path corresponding to
5759 Continuing, but uninstalled executables may not work.
5761 This should not cause the build to fail. At worst, it means that the
5762 wrapper executable will specify file names or paths appropriate for the
5763 build platform. Since those are not appropriate for the host platform,
5764 the uninstalled executables would not operate correctly, even when the
5765 wrapper executable is launched via the appropriate emulation or
5766 API-enhancement (e.g. Wine). Simply install the executables on the
5767 host platform, and execute them there.
5770 File: libtool.info, Node: Native MinGW File Name Conversion, Next: Cygwin/Windows File Name Conversion, Prev: File Name Conversion Failure, Up: File name conversion
5772 15.3.7.2 Native MinGW File Name Conversion
5773 ..........................................
5775 MSYS is a Unix emulation environment for Windows, and is specifically
5776 designed such that in normal usage it _pretends_ to be MinGW or native
5777 Windows, but understands Unix-style file names and paths, and supports
5778 standard Unix tools and shells. Thus, "native" MinGW builds are
5779 actually an odd sort of cross-compile, from an MSYS Unix emulation
5780 environment "pretending" to be MinGW, to actual native Windows.
5782 When an MSYS shell launches a native Windows executable (as opposed
5783 to other _MSYS_ executables), it uses a system of heuristics to detect
5784 any command-line arguments that contain file names or paths. It
5785 automatically converts these file names from the MSYS (Unix-like)
5786 format, to the corresponding Windows file name, before launching the
5787 executable. However, this auto-conversion facility is only available
5788 when using the MSYS runtime library. The wrapper executable itself is
5789 a MinGW application (that is, it does not use the MSYS runtime
5790 library). The wrapper executable must set `PATH' to, and call
5791 `_spawnv' with, values that have already been converted from MSYS
5792 format to Windows. Thus, when libtool writes the source code for the
5793 wrapper executable, it must manually convert MSYS paths to Windows
5794 format, so that the Windows values can be hard-coded into the wrapper
5798 File: libtool.info, Node: Cygwin/Windows File Name Conversion, Next: Unix/Windows File Name Conversion, Prev: Native MinGW File Name Conversion, Up: File name conversion
5800 15.3.7.3 Cygwin/Windows File Name Conversion
5801 ............................................
5803 Cygwin provides a Unix emulation environment for Windows. As part of
5804 that emulation, it provides a file system mapping that presents the
5805 Windows file system in a Unix-compatible manner. Cygwin also provides
5806 a utility `cygpath' that can be used to convert file names and paths
5807 between the two representations. In a correctly configured Cygwin
5808 installation, `cygpath' is always present, and is in the `PATH'.
5810 Libtool uses `cygpath' to convert from Cygwin (Unix-style) file names
5811 and paths to Windows format when the build platform is Cygwin and the
5812 host platform is MinGW.
5814 When the host platform is Cygwin, but the build platform is MSYS or
5815 some Unix system, libtool also uses `cygpath' to convert from Windows
5816 to Cygwin format (after first converting from the build platform format
5817 to Windows format; see *note Native MinGW File Name Conversion:: and
5818 *note Unix/Windows File Name Conversion::). Because the build platform
5819 is not Cygwin, `cygpath' is not (and should not be) in the `PATH'.
5820 Therefore, in this configuration the environment variable `LT_CYGPATH'
5821 is required. *Note LT_CYGPATH::.
5824 File: libtool.info, Node: Unix/Windows File Name Conversion, Next: LT_CYGPATH, Prev: Cygwin/Windows File Name Conversion, Up: File name conversion
5826 15.3.7.4 Unix/Windows File Name Conversion
5827 ..........................................
5829 Wine (http://www.winehq.org/) provides an interpretation environment for
5830 some Unix platforms in which Windows applications can be executed. It
5831 provides a mapping between the Unix file system and a virtual Windows
5832 file system used by the Windows programs. For the file name conversion
5833 to work, Wine must be installed and properly configured on the build
5834 platform, and the `winepath' application must be in the build
5835 platform's `PATH'. In addition, on 32bit GNU/Linux it is usually
5836 helpful if the binfmt extension is enabled.
5839 File: libtool.info, Node: LT_CYGPATH, Next: Cygwin to MinGW Cross, Prev: Unix/Windows File Name Conversion, Up: File name conversion
5844 For some cross-compile configurations (where the host platform is
5845 Cygwin), the `cygpath' program is used to convert file names from the
5846 build platform notation to the Cygwin form (technically, this
5847 conversion is from Windows notation to Cygwin notation; the conversion
5848 from the build platform format to Windows notation is performed via
5849 other means). However, because the `cygpath' program is not (and
5850 should not be) in the `PATH' on the build platform, `LT_CYGPATH' must
5851 specify the full build platform file name (that is, the full Unix or
5852 MSYS file name) of the `cygpath' program.
5854 The reason `cygpath' should not be in the build platform `PATH' is
5855 twofold: first, `cygpath' is usually installed in the same directory as
5856 many other Cygwin executables, such as `sed', `cp', etc. If the build
5857 platform environment had this directory in its `PATH', then these
5858 Cygwin versions of common Unix utilities might be used in preference to
5859 the ones provided by the build platform itself, with deleterious
5860 effects. Second, especially when Cygwin-1.7 or later is used, multiple
5861 Cygwin installations can coexist within the same Windows instance.
5862 Each installation will have separate "mount tables" specified in
5863 `CYGROOT-N/etc/fstab'. These "mount tables" control how that instance
5864 of Cygwin will map Windows file names and paths to Cygwin form. Each
5865 installation's `cygpath' utility automatically deduces the appropriate
5866 `/etc/fstab' file. Since each `CYGROOT-N/etc/fstab' mount table may
5867 specify different mappings, it matters which `cygpath' is used.
5869 Note that `cygpath' is a Cygwin application; to execute this tool
5870 from Unix requires a working and properly configured Wine installation,
5871 as well as enabling the GNU/Linux `binfmt' extension. Furthermore, the
5872 Cygwin `setup.exe' tool should have been used, via Wine, to properly
5873 install Cygwin into the Wine file system (and registry).
5875 Unfortunately, Wine support for Cygwin is intermittent. Recent
5876 releases of Cygwin (1.7 and above) appear to require more Windows API
5877 support than Wine provides (as of Wine version 1.2); most Cygwin
5878 applications fail to execute. This includes `cygpath' itself. Hence,
5879 it is best _not_ to use the LT_CYGPATH machinery in libtool when
5880 performing Unix to Cygwin cross-compiles. Similarly, it is best _not_
5881 to enable the GNU/Linux binfmt support in this configuration, because
5882 while Wine will fail to execute the compiled Cygwin applications, it
5883 will still exit with status zero. This tends to confuse build systems
5884 and test suites (including libtool's own testsuite, resulting in
5885 spurious reported failures). Wine support for the older Cygwin-1.5
5886 series appears satisfactory, but the Cygwin team no longer supports
5887 Cygwin-1.5. It is hoped that Wine will eventually be improved such that
5888 Cygwin-1.7 will again operate correctly under Wine. Until then,
5889 libtool will report warnings as described in *note File Name Conversion
5890 Failure:: in these scenarios.
5892 However, `LT_CYGPATH' is also used for the MSYS to Cygwin cross
5893 compile scenario, and operates as expected.
5896 File: libtool.info, Node: Cygwin to MinGW Cross, Prev: LT_CYGPATH, Up: File name conversion
5898 15.3.7.6 Cygwin to MinGW Cross
5899 ..............................
5901 There are actually three different scenarios that could all
5902 legitimately be called a "Cygwin to MinGW" cross compile. The current
5903 (and standard) definition is when there is a compiler that produces
5904 native Windows libraries and applications, but which itself is a Cygwin
5905 application, just as would be expected in any other cross compile setup.
5907 However, historically there were two other definitions, which we
5908 will refer to as the _fake_ one, and the _lying_ one.
5910 In the _fake_ Cygwin to MinGW cross compile case, you actually use a
5911 native MinGW compiler, but you do so from within a Cygwin environment:
5913 export PATH="/c/MinGW/bin:${PATH}"
5914 configure --build=i686-pc-cygwin \
5916 NM=/c/MinGW/bin/nm.exe
5918 In this way, the build system "knows" that you are cross compiling,
5919 and the file name conversion logic will be used. However, because the
5920 tools (`mingw32-gcc', `nm', `ar') used are actually native Windows
5921 applications, they will not understand any Cygwin (that is, Unix-like)
5922 absolute file names passed as command line arguments (and, unlike MSYS,
5923 Cygwin does not automatically convert such arguments). However, so
5924 long as only relative file names are used in the build system, and
5925 non-Windows-supported Unix idioms such as symlinks and mount points are
5926 avoided, this scenario should work.
5928 If you must use absolute file names, you will have to force Libtool
5929 to convert file names for the toolchain in this case, by doing the
5930 following before you run configure:
5932 export lt_cv_to_tool_file_cmd=func_convert_file_cygwin_to_w32
5934 In the _lying_ Cygwin to MinGW cross compile case, you lie to the
5937 export PATH="/c/MinGW/bin:${PATH}"
5938 configure --build=i686-pc-mingw32 \
5939 --host=i686-pc-mingw32 \
5940 --disable-dependency-tracking
5942 and claim that the build platform is MinGW, even though you are actually
5943 running under _Cygwin_ and not MinGW. In this case, libtool does _not_
5944 know that you are performing a cross compile, and thinks instead that
5945 you are performing a native MinGW build. However, as described in
5946 (*note Native MinGW File Name Conversion::), that scenario triggers an
5947 "MSYS to Windows" file name conversion. This, of course, is the wrong
5948 conversion since we are actually running under Cygwin. Also, the
5949 toolchain is expecting Windows file names (not Cygwin) but unless told
5950 so Libtool will feed Cygwin file names to the toolchain in this case.
5951 To force the correct file name conversions in this situation, you
5952 should do the following _before_ running configure:
5954 export lt_cv_to_host_file_cmd=func_convert_file_cygwin_to_w32
5955 export lt_cv_to_tool_file_cmd=func_convert_file_cygwin_to_w32
5957 Note that this relies on internal implementation details of libtool,
5958 and is subject to change. Also, `--disable-dependency-tracking' is
5959 required, because otherwise the MinGW GCC will generate dependency
5960 files that contain Windows file names. This, in turn, will confuse the
5961 Cygwin `make' program, which does not accept Windows file names:
5963 Makefile:1: *** target pattern contains no `%'. Stop.
5965 There have also always been a number of other details required for
5966 the _lying_ case to operate correctly, such as the use of so-called
5969 # CYGWIN-ROOT/etc/fstab
5970 D:/foo /foo some_fs binary 0 0
5971 D:/bar /bar some_fs binary 0 0
5972 E:/grill /grill some_fs binary 0 0
5974 In this way, top-level directories of each drive are available using
5975 identical names within Cygwin.
5977 Note that you also need to ensure that the standard Unix directories
5978 (like `/bin', `/lib', `/usr', `/etc') appear in the root of a drive.
5979 This means that you must install Cygwin itself into the `C:/' root
5980 directory (or `D:/', or `E:/', etc)--instead of the recommended
5981 installation into `C:/cygwin/'. In addition, all file names used in
5982 the build system must be relative, symlinks should not be used within
5983 the source or build directory trees, and all `-M*' options to `gcc'
5984 except `-MMD' must be avoided.
5986 This is quite a fragile setup, but it has been in historical use,
5987 and so is documented here.
5990 File: libtool.info, Node: Windows DLLs, Prev: File name conversion, Up: Platform quirks
5995 This topic describes a couple of ways to portably create Windows Dynamic
5996 Link Libraries (DLLs). Libtool knows how to create DLLs using GNU tools
5997 and using Microsoft tools.
5999 A typical library has a "hidden" implementation with an interface
6000 described in a header file. On just about every system, the interface
6001 could be something like this:
6014 And the implementation could be something like this:
6027 return three - one ();
6032 When using contemporary GNU tools to create the Windows DLL, the
6033 above code will work there too, thanks to its auto-import/auto-export
6034 features. But that is not the case when using older GNU tools or
6035 perhaps more interestingly when using proprietary tools. In those
6036 cases the code will need additional decorations on the interface
6037 symbols with `__declspec(dllimport)' and `__declspec(dllexport)'
6038 depending on whether the library is built or it's consumed and how it's
6039 built and consumed. However, it should be noted that it would have
6040 worked also with Microsoft tools, if only the variable `three' hadn't
6041 been there, due to the fact the Microsoft tools will automatically
6042 import functions (but sadly not variables) and Libtool will
6043 automatically export non-static symbols as described next.
6045 With Microsoft tools, Libtool digs through the object files that
6046 make up the library, looking for non-static symbols to automatically
6047 export. I.e., Libtool with Microsoft tools tries to mimic the
6048 auto-export feature of contemporary GNU tools. It should be noted that
6049 the GNU auto-export feature is turned off when an explicit
6050 `__declspec(dllexport)' is seen. The GNU tools do this to not make
6051 more symbols visible for projects that have already taken the trouble
6052 to decorate symbols. There is no similar way to limit which symbols
6053 are visible in the code when Libtool is using Microsoft tools. In
6054 order to limit symbol visibility in that case you need to use one of
6055 the options `-export-symbols' or `-export-symbols-regex'.
6057 No matching help with auto-import is provided by Libtool, which is
6058 why variables must be decorated to import them from a DLL for
6059 everything but contemporary GNU tools. As stated above, functions are
6060 automatically imported by both contemporary GNU tools and Microsoft
6061 tools, but for other proprietary tools the auto-import status of
6062 functions is unknown.
6064 When the objects that form the library are built, there are generally
6065 two copies built for each object. One copy is used when linking the DLL
6066 and one copy is used for the static library. On Windows systems, a pair
6067 of defines are commonly used to discriminate how the interface symbols
6068 should be decorated. The first define is `-DDLL_EXPORT' which is
6069 automatically provided by Libtool when `libtool' builds the copy of the
6070 object that is destined for the DLL. The second define is
6071 `-DLIBFOO_BUILD' (or similar) which is often added by the package
6072 providing the library and is used when building the library, but not
6073 when consuming the library.
6075 However, the matching double compile is not performed when consuming
6076 libraries. It is therefore not possible to reliably distinguish if the
6077 consumer is importing from a DLL or if it is going to use a static
6080 With contemporary GNU tools, auto-import often saves the day, but see
6081 the GNU ld documentation and its `--enable-auto-import' option for some
6082 corner cases when it does not (*note `--enable-auto-import':
6085 With Microsoft tools you typically get away with always compiling the
6086 code such that variables are expected to be imported from a DLL and
6087 functions are expected to be found in a static library. The tools will
6088 then automatically import the function from a DLL if that is where they
6089 are found. If the variables are not imported from a DLL as expected,
6090 but are found in a static library that is otherwise pulled in by some
6091 function, the linker will issue a warning (LNK4217) that a locally
6092 defined symbol is imported, but it still works. In other words, this
6093 scheme will not work to only consume variables from a library. There is
6094 also a price connected to this liberal use of imports in that an extra
6095 indirection is introduced when you are consuming the static version of
6096 the library. That extra indirection is unavoidable when the DLL is
6097 consumed, but it is not needed when consuming the static library.
6099 For older GNU tools and other proprietary tools there is no generic
6100 way to make it possible to consume either of the DLL or the static
6101 library without user intervention, the tools need to be told what is
6102 intended. One common assumption is that if a DLL is being built
6103 (`DLL_EXPORT' is defined) then that DLL is going to consume any
6104 dependent libraries as DLLs. If that assumption is made everywhere, it
6105 is possible to select how an end-user application is consuming
6106 libraries by adding a single flag `-DDLL_EXPORT' when a DLL build is
6107 required. This is of course an all or nothing deal, either everything
6108 as DLLs or everything as static libraries.
6110 To sum up the above, the header file of the foo library needs to be
6111 changed into something like this:
6118 #if defined _WIN32 && !defined __GNUC__
6119 # ifdef LIBFOO_BUILD
6121 # define LIBFOO_SCOPE __declspec (dllexport)
6122 # define LIBFOO_SCOPE_VAR extern __declspec (dllexport)
6124 # elif defined _MSC_VER
6125 # define LIBFOO_SCOPE
6126 # define LIBFOO_SCOPE_VAR extern __declspec (dllimport)
6127 # elif defined DLL_EXPORT
6128 # define LIBFOO_SCOPE __declspec (dllimport)
6129 # define LIBFOO_SCOPE_VAR extern __declspec (dllimport)
6132 #ifndef LIBFOO_SCOPE
6133 # define LIBFOO_SCOPE
6134 # define LIBFOO_SCOPE_VAR extern
6137 LIBFOO_SCOPE int one (void);
6138 LIBFOO_SCOPE int two (void);
6139 LIBFOO_SCOPE_VAR int three;
6143 When the targets are limited to contemporary GNU tools and Microsoft
6144 tools, the above can be simplified to the following:
6151 #if defined _WIN32 && !defined __GNUC__ && !defined LIBFOO_BUILD
6152 # define LIBFOO_SCOPE_VAR extern __declspec (dllimport)
6154 # define LIBFOO_SCOPE_VAR extern
6159 LIBFOO_SCOPE_VAR int three;
6163 This last simplified version can of course only work when Libtool is
6164 used to build the DLL, as no symbols would be exported otherwise (i.e.,
6165 when using Microsoft tools).
6167 It should be noted that there are various projects that attempt to
6168 relax these requirements by various low level tricks, but they are not
6169 discussed here. Examples are FlexDLL
6170 (http://alain.frisch.fr/flexdll.html) and edll
6171 (http://edll.sourceforge.net/).
6174 File: libtool.info, Node: libtool script contents, Next: Cheap tricks, Prev: Platform quirks, Up: Maintaining
6176 15.4 `libtool' script contents
6177 ==============================
6179 Since version 1.4, the `libtool' script is generated by `configure'
6180 (*note Configuring::). In earlier versions, `configure' achieved this
6181 by calling a helper script called `ltconfig'. From libtool version 0.7
6182 to 1.0, this script simply set shell variables, then sourced the
6183 libtool backend, `ltmain.sh'. `ltconfig' from libtool version 1.1
6184 through 1.3 inlined the contents of `ltmain.sh' into the generated
6185 `libtool', which improved performance on many systems. The tests that
6186 `ltconfig' used to perform are now kept in `libtool.m4' where they can
6187 be written using Autoconf. This has the runtime performance benefits
6188 of inlined `ltmain.sh', _and_ improves the build time a little while
6189 considerably easing the amount of raw shell code that used to need
6192 The convention used for naming variables that hold shell commands for
6193 delayed evaluation, is to use the suffix `_cmd' where a single line of
6194 valid shell script is needed, and the suffix `_cmds' where multiple
6195 lines of shell script *may* be delayed for later evaluation. By
6196 convention, `_cmds' variables delimit the evaluation units with the `~'
6197 character where necessary.
6199 Here is a listing of each of the configuration variables, and how
6200 they are used within `ltmain.sh' (*note Configuring::):
6203 The name of the system library archiver.
6206 The name of the compiler used to configure libtool. This will
6207 always contain the compiler for the current language (*note
6211 An `echo' program that does not interpret backslashes as an escape
6212 character. It may be given only one argument, so due quoting is
6216 The name of the linker that libtool should use internally for
6217 reloadable linking and possibly shared libraries.
6220 -- Variable: LTCFLAGS
6221 The name of the C compiler and C compiler flags used to configure
6225 The name of a BSD- or MS-compatible program that produces listings
6226 of global symbols. For BSD `nm', the symbols should be in one the
6229 ADDRESS C GLOBAL-VARIABLE-NAME
6230 ADDRESS D GLOBAL-VARIABLE-NAME
6231 ADDRESS T GLOBAL-FUNCTION-NAME
6233 For MS `dumpbin', the symbols should be in one of the following
6236 COUNTER SIZE UNDEF notype External | GLOBAL-VAR
6237 COUNTER ADDRESS SECTION notype External | GLOBAL-VAR
6238 COUNTER ADDRESS SECTION notype () External | GLOBAL-FUNC
6240 The SIZE of the global variables are not zero and the SECTION of
6241 the global functions are not "UNDEF". Symbols in "pick any"
6242 sections ("pick any" appears in the section header) are not global
6246 Set to the name of the `ranlib' program, if any.
6248 -- Variable: allow_undefined_flag
6249 The flag that is used by `archive_cmds' in order to declare that
6250 there will be unresolved symbols in the resulting shared library.
6251 Empty, if no such flag is required. Set to `unsupported' if there
6252 is no way to generate a shared library with references to symbols
6253 that aren't defined in that library.
6255 -- Variable: always_export_symbols
6256 Whether libtool should automatically generate a list of exported
6257 symbols using `export_symbols_cmds' before linking an archive.
6258 Set to `yes' or `no'. Default is `no'.
6260 -- Variable: archive_cmds
6261 -- Variable: archive_expsym_cmds
6262 -- Variable: old_archive_cmds
6263 Commands used to create shared libraries, shared libraries with
6264 `-export-symbols' and static libraries, respectively.
6266 -- Variable: archiver_list_spec
6267 Specify filename containing input files for `AR'.
6269 -- Variable: old_archive_from_new_cmds
6270 If the shared library depends on a static library,
6271 `old_archive_from_new_cmds' contains the commands used to create
6272 that static library. If this variable is not empty,
6273 `old_archive_cmds' is not used.
6275 -- Variable: old_archive_from_expsyms_cmds
6276 If a static library must be created from the export symbol list in
6277 order to correctly link with a shared library,
6278 `old_archive_from_expsyms_cmds' contains the commands needed to
6279 create that static library. When these commands are executed, the
6280 variable `soname' contains the name of the shared library in
6281 question, and the `$objdir/$newlib' contains the path of the
6282 static library these commands should build. After executing these
6283 commands, libtool will proceed to link against `$objdir/$newlib'
6284 instead of `soname'.
6286 -- Variable: lock_old_archive_extraction
6287 Set to `yes' if the extraction of a static library requires locking
6288 the library file. This is required on Darwin.
6291 -- Variable: build_alias
6292 -- Variable: build_os
6293 Set to the specified and canonical names of the system that
6294 libtool was built on.
6296 -- Variable: build_libtool_libs
6297 Whether libtool should build shared libraries on this system. Set
6300 -- Variable: build_old_libs
6301 Whether libtool should build static libraries on this system. Set
6304 -- Variable: compiler_c_o
6305 Whether the compiler supports the `-c' and `-o' options
6306 simultaneously. Set to `yes' or `no'.
6308 -- Variable: compiler_needs_object
6309 Whether the compiler has to see an object listed on the command
6310 line in order to successfully invoke the linker. If `no', then a
6311 set of convenience archives or a set of object file names can be
6312 passed via linker-specific options or linker scripts.
6314 -- Variable: dlopen_support
6315 Whether `dlopen' is supported on the platform. Set to `yes' or
6318 -- Variable: dlopen_self
6319 Whether it is possible to `dlopen' the executable itself. Set to
6322 -- Variable: dlopen_self_static
6323 Whether it is possible to `dlopen' the executable itself, when it
6324 is linked statically (`-all-static'). Set to `yes' or `no'.
6326 -- Variable: exclude_expsyms
6327 List of symbols that should not be listed in the preloaded symbols.
6329 -- Variable: export_dynamic_flag_spec
6330 Compiler link flag that allows a dlopened shared library to
6331 reference symbols that are defined in the program.
6333 -- Variable: export_symbols_cmds
6334 Commands to extract exported symbols from `libobjs' to the file
6337 -- Variable: extract_expsyms_cmds
6338 Commands to extract the exported symbols list from a shared
6339 library. These commands are executed if there is no file
6340 `$objdir/$soname-def', and should write the names of the exported
6341 symbols to that file, for the use of
6342 `old_archive_from_expsyms_cmds'.
6344 -- Variable: fast_install
6345 Determines whether libtool will privilege the installer or the
6346 developer. The assumption is that installers will seldom run
6347 programs in the build tree, and the developer will seldom install.
6348 This is only meaningful on platforms where
6349 `shlibpath_overrides_runpath' is not `yes', so `fast_install' will
6350 be set to `needless' in this case. If `fast_install' set to
6351 `yes', libtool will create programs that search for installed
6352 libraries, and, if a program is run in the build tree, a new copy
6353 will be linked on-demand to use the yet-to-be-installed libraries.
6354 If set to `no', libtool will create programs that use the
6355 yet-to-be-installed libraries, and will link a new copy of the
6356 program at install time. The default value is `yes' or
6357 `needless', depending on platform and configuration flags, and it
6358 can be turned from `yes' to `no' with the configure flag
6359 `--disable-fast-install'.
6361 On some systems, the linker always hardcodes paths to dependent
6362 libraries into the output. In this case, `fast_install' is never
6363 set to `yes', and relinking at install time is triggered. This
6364 also means that `DESTDIR' installation does not work as expected.
6366 -- Variable: file_magic_glob
6367 How to find potential files when `deplibs_check_method' is
6368 `file_magic'. `file_magic_glob' is a `sed' expression, and the
6369 `sed' instance is fed potential file names that are transformed by
6370 the `file_magic_glob' expression. Useful when the shell does not
6371 support the shell option `nocaseglob', making `want_nocaseglob'
6372 inappropriate. Normally disabled (i.e. `file_magic_glob' is
6375 -- Variable: finish_cmds
6376 Commands to tell the dynamic linker how to find shared libraries
6377 in a specific directory.
6379 -- Variable: finish_eval
6380 Same as `finish_cmds', except the commands are not displayed.
6382 -- Variable: global_symbol_pipe
6383 A pipeline that takes the output of `NM', and produces a listing of
6384 raw symbols followed by their C names. For example:
6386 $ eval "$NM progname | $global_symbol_pipe"
6393 The first column contains the symbol type (used to tell data from
6394 code) but its meaning is system dependent.
6396 -- Variable: global_symbol_to_cdecl
6397 A pipeline that translates the output of `global_symbol_pipe' into
6398 proper C declarations. Since some platforms, such as HP/UX, have
6399 linkers that differentiate code from data, data symbols are
6400 declared as data, and code symbols are declared as functions.
6402 -- Variable: hardcode_action
6403 Either `immediate' or `relink', depending on whether shared
6404 library paths can be hardcoded into executables before they are
6405 installed, or if they need to be relinked.
6407 -- Variable: hardcode_direct
6408 Set to `yes' or `no', depending on whether the linker hardcodes
6409 directories if a library is directly specified on the command line
6410 (such as `DIR/libNAME.a') when `hardcode_libdir_flag_spec' is
6413 -- Variable: hardcode_direct_absolute
6414 Some architectures hardcode "absolute" library directories that
6415 can not be overridden by `shlibpath_var' when `hardcode_direct' is
6416 `yes'. In that case set `hardcode_direct_absolute' to `yes', or
6419 -- Variable: hardcode_into_libs
6420 Whether the platform supports hardcoding of run-paths into
6421 libraries. If enabled, linking of programs will be much simpler
6422 but libraries will need to be relinked during installation. Set
6425 -- Variable: hardcode_libdir_flag_spec
6426 Flag to hardcode a `libdir' variable into a binary, so that the
6427 dynamic linker searches `libdir' for shared libraries at runtime.
6428 If it is empty, libtool will try to use some other hardcoding
6431 -- Variable: hardcode_libdir_separator
6432 If the compiler only accepts a single `hardcode_libdir_flag', then
6433 this variable contains the string that should separate multiple
6434 arguments to that flag.
6436 -- Variable: hardcode_minus_L
6437 Set to `yes' or `no', depending on whether the linker hardcodes
6438 directories specified by `-L' flags into the resulting executable
6439 when `hardcode_libdir_flag_spec' is specified.
6441 -- Variable: hardcode_shlibpath_var
6442 Set to `yes' or `no', depending on whether the linker hardcodes
6443 directories by writing the contents of `$shlibpath_var' into the
6444 resulting executable when `hardcode_libdir_flag_spec' is
6445 specified. Set to `unsupported' if directories specified by
6446 `$shlibpath_var' are searched at run time, but not at link time.
6449 -- Variable: host_alias
6450 -- Variable: host_os
6451 Set to the specified and canonical names of the system that
6452 libtool was configured for.
6454 -- Variable: include_expsyms
6455 List of symbols that must always be exported when using
6458 -- Variable: inherit_rpath
6459 Whether the linker adds runtime paths of dependency libraries to
6460 the runtime path list, requiring libtool to relink the output when
6461 installing. Set to `yes' or `no'. Default is `no'.
6463 -- Variable: install_override_mode
6464 Permission mode override for installation of shared libraries. If
6465 the runtime linker fails to load libraries with wrong permissions,
6466 then it may fail to execute programs that are needed during
6467 installation, because these need the library that has just been
6468 installed. In this case, it is necessary to pass the mode to
6469 `install' with `-m INSTALL_OVERRIDE_MODE'.
6472 The standard old archive suffix (normally `a').
6474 -- Variable: libname_spec
6475 The format of a library name prefix. On all Unix systems, static
6476 libraries are called `libNAME.a', but on some systems (such as
6477 OS/2 or MS-DOS), the library is just called `NAME.a'.
6479 -- Variable: library_names_spec
6480 A list of shared library names. The first is the name of the file,
6481 the rest are symbolic links to the file. The name in the list is
6482 the file name that the linker finds when given `-lNAME'.
6484 -- Variable: link_all_deplibs
6485 Whether libtool must link a program against all its dependency
6486 libraries. Set to `yes' or `no'. Default is `unknown', which is
6487 a synonym for `yes'.
6489 -- Variable: link_static_flag
6490 Linker flag (passed through the C compiler) used to prevent dynamic
6493 -- Variable: macro_version
6494 -- Variable: macro_revision
6495 The release and revision from which the libtool.m4 macros were
6496 taken. This is used to ensure that macros and `ltmain.sh'
6497 correspond to the same Libtool version.
6499 -- Variable: max_cmd_len
6500 The approximate longest command line that can be passed to `$SHELL'
6501 without being truncated, as computed by `LT_CMD_MAX_LEN'.
6503 -- Variable: need_lib_prefix
6504 Whether we can `dlopen' modules without a `lib' prefix. Set to
6505 `yes' or `no'. By default, it is `unknown', which means the same
6506 as `yes', but documents that we are not really sure about it.
6507 `no' means that it is possible to `dlopen' a module without the
6510 -- Variable: need_version
6511 Whether versioning is required for libraries, i.e. whether the
6512 dynamic linker requires a version suffix for all libraries. Set
6513 to `yes' or `no'. By default, it is `unknown', which means the
6514 same as `yes', but documents that we are not really sure about it.
6516 -- Variable: need_locks
6517 Whether files must be locked to prevent conflicts when compiling
6518 simultaneously. Set to `yes' or `no'.
6520 -- Variable: nm_file_list_spec
6521 Specify filename containing input files for `NM'.
6523 -- Variable: no_builtin_flag
6524 Compiler flag to disable builtin functions that conflict with
6525 declaring external global symbols as `char'.
6527 -- Variable: no_undefined_flag
6528 The flag that is used by `archive_cmds' in order to declare that
6529 there will be no unresolved symbols in the resulting shared
6530 library. Empty, if no such flag is required.
6533 The name of the directory that contains temporary libtool files.
6536 The standard object file suffix (normally `o').
6538 -- Variable: pic_flag
6539 Any additional compiler flags for building library object files.
6541 -- Variable: postinstall_cmds
6542 -- Variable: old_postinstall_cmds
6543 Commands run after installing a shared or static library,
6546 -- Variable: postuninstall_cmds
6547 -- Variable: old_postuninstall_cmds
6548 Commands run after uninstalling a shared or static library,
6551 -- Variable: postlink_cmds
6552 Commands necessary for finishing linking programs. `postlink_cmds'
6553 are executed immediately after the program is linked. Any
6554 occurrence of the string `@OUTPUT@' in `postlink_cmds' is replaced
6555 by the name of the created executable (i.e. not the wrapper, if a
6556 wrapper is generated) prior to execution. Similarly,
6557 `@TOOL_OUTPUT@' is replaced by the toolchain format of `@OUTPUT@'.
6558 Normally disabled (i.e. `postlink_cmds' empty).
6560 -- Variable: reload_cmds
6561 -- Variable: reload_flag
6562 Commands to create a reloadable object. Set `reload_cmds' to
6563 `false' on systems that cannot create reloadable objects.
6565 -- Variable: runpath_var
6566 The environment variable that tells the linker which directories to
6567 hardcode in the resulting executable.
6569 -- Variable: shlibpath_overrides_runpath
6570 Indicates whether it is possible to override the hard-coded library
6571 search path of a program with an environment variable. If this is
6572 set to no, libtool may have to create two copies of a program in
6573 the build tree, one to be installed and one to be run in the build
6574 tree only. When each of these copies is created depends on the
6575 value of `fast_install'. The default value is `unknown', which is
6578 -- Variable: shlibpath_var
6579 The environment variable that tells the dynamic linker where to
6580 find shared libraries.
6582 -- Variable: soname_spec
6583 The name coded into shared libraries, if different from the real
6586 -- Variable: striplib
6587 -- Variable: old_striplib
6588 Command to strip a shared (`striplib') or static (`old_striplib')
6589 library, respectively. If these variables are empty, the strip
6590 flag in the install mode will be ignored for libraries (*note
6593 -- Variable: sys_lib_dlsearch_path_spec
6594 Expression to get the run-time system library search path.
6595 Directories that appear in this list are never hard-coded into
6598 -- Variable: sys_lib_search_path_spec
6599 Expression to get the compile-time system library search path.
6600 This variable is used by libtool when it has to test whether a
6601 certain library is shared or static. The directories listed in
6602 `shlibpath_var' are automatically appended to this list, every time
6603 libtool runs (i.e., not at configuration time), because some
6604 linkers use this variable to extend the library search path.
6605 Linker switches such as `-L' also augment the search path.
6607 -- Variable: thread_safe_flag_spec
6608 Linker flag (passed through the C compiler) used to generate
6609 thread-safe libraries.
6611 -- Variable: to_host_file_cmd
6612 If the toolchain is not native to the build platform (e.g. if you
6613 are using MSYS to drive the scripting, but are using the MinGW
6614 native Windows compiler) this variable describes how to convert
6615 file names from the format used by the build platform to the
6616 format used by host platform. Normally set to
6617 `func_convert_file_noop', libtool will autodetect most cases in
6618 which other values should be used. On rare occasions, it may be
6619 necessary to override the autodetected value (*note Cygwin to
6622 -- Variable: to_tool_file_cmd
6623 If the toolchain is not native to the build platform (e.g. if you
6624 are using some Unix to drive the scripting together with a Windows
6625 toolchain running in Wine) this variable describes how to convert
6626 file names from the format used by the build platform to the
6627 format used by the toolchain. Normally set to
6628 `func_convert_file_noop'.
6630 -- Variable: version_type
6631 The library version numbering type. One of `libtool',
6632 `freebsd-aout', `freebsd-elf', `irix', `linux', `osf', `sunos',
6633 `windows', or `none'.
6635 -- Variable: want_nocaseglob
6636 Find potential files using the shell option `nocaseglob', when
6637 `deplibs_check_method' is `file_magic'. Normally set to `no'. Set
6638 to `yes' to enable the `nocaseglob' shell option when looking for
6639 potential file names in a case-insensitive manner.
6641 -- Variable: whole_archive_flag_spec
6642 Compiler flag to generate shared objects from convenience archives.
6645 The C compiler flag that allows libtool to pass a flag directly to
6646 the linker. Used as: `${wl}SOME-FLAG'.
6648 Variables ending in `_cmds' or `_eval' contain a `~'-separated list
6649 of commands that are `eval'ed one after another. If any of the
6650 commands return a nonzero exit status, libtool generally exits with an
6653 Variables ending in `_spec' are `eval'ed before being used by
6657 File: libtool.info, Node: Cheap tricks, Prev: libtool script contents, Up: Maintaining
6662 Here are a few tricks that you can use in order to make maintainership
6665 * When people report bugs, ask them to use the `--config',
6666 `--debug', or `--features' flags, if you think they will help you.
6667 These flags are there to help you get information directly, rather
6668 than having to trust second-hand observation.
6670 * Rather than reconfiguring libtool every time I make a change to
6671 `ltmain.in', I keep a permanent `libtool' script in my `PATH',
6672 which sources `ltmain.in' directly.
6674 The following steps describe how to create such a script, where
6675 `/home/src/libtool' is the directory containing the libtool source
6676 tree, `/home/src/libtool/libtool' is a libtool script that has been
6677 configured for your platform, and `~/bin' is a directory in your
6681 trick$ sed 's%^\(macro_version=\).*$%\1@VERSION@%;
6682 s%^\(macro_revision=\).*$%\1@package_revision@%;
6683 /^# ltmain\.sh/q' /home/src/libtool/libtool > libtool
6684 trick$ echo '. /home/src/libtool/ltmain.in' >> libtool
6685 trick$ chmod +x libtool
6686 trick$ libtool --version
6687 ltmain.sh (GNU @PACKAGE@@TIMESTAMP@) @VERSION@
6689 Copyright (C) 2011 Free Software Foundation, Inc.
6690 This is free software; see the source for copying conditions. There is NO
6691 warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
6694 The output of the final `libtool --version' command shows that the
6695 `ltmain.in' script is being used directly. Now, modify `~/bin/libtool'
6696 or `/home/src/libtool/ltmain.in' directly in order to test new changes
6697 without having to rerun `configure'.