1This is ../../libtool/doc/libtool.info, produced by makeinfo version 24.7 from ../../libtool/doc/libtool.texi. 3 4INFO-DIR-SECTION GNU programming tools 5START-INFO-DIR-ENTRY 6* Libtool: (libtool). Generic shared library support script. 7END-INFO-DIR-ENTRY 8 9INFO-DIR-SECTION Individual utilities 10START-INFO-DIR-ENTRY 11* libtoolize: (libtool)Invoking libtoolize. Adding libtool support. 12END-INFO-DIR-ENTRY 13 14 This file documents GNU Libtool 1.5.20 15 16 Copyright (C) 1996-2003, 2005 Free Software Foundation, Inc. 17 18 Permission is granted to copy, distribute and/or modify this document 19under the terms of the GNU Free Documentation License, Version 1.1 or 20any later version published by the Free Software Foundation; with the 21no Invariant Sections, with no Front-Cover Texts, and with no 22Back-Cover Texts. A copy of the license is included in the section 23entitled "GNU Free Documentation License". 24 25 26File: libtool.info, Node: Top, Next: Introduction, Prev: (dir), Up: (dir) 27 28Shared library support for GNU 29****************************** 30 31This file documents GNU Libtool, a script that allows package developers 32to provide generic shared library support. This edition documents 33version 1.5.20. 34 35 *Note Reporting bugs::, for information on how to report problems 36with libtool. 37 38* Menu: 39 40* Introduction:: What the heck is libtool? 41* Libtool paradigm:: How libtool's view of libraries is different. 42* Using libtool:: Example of using libtool to build libraries. 43* Invoking libtool:: Running the `libtool' script. 44* Integrating libtool:: Using libtool in your own packages. 45* Versioning:: Using library interface versions. 46* Library tips:: Tips for library interface design. 47* Inter-library dependencies:: Libraries that depend on other libraries. 48* Dlopened modules:: `dlopen'ing libtool-created libraries. 49* Using libltdl:: Libtool's portable `dlopen' wrapper library. 50* Other languages:: Using libtool without a C compiler. 51* Troubleshooting:: When libtool doesn't work as advertised. 52* Maintaining:: Information used by the libtool maintainer. 53* GNU Free Documentation License:: License for this manual. 54* Index:: Full index. 55 56 57Introduction 58 59* Motivation:: Why does GNU need a libtool? 60* Issues:: The problems that need to be addressed. 61* Other implementations:: How other people have solved these issues. 62* Postmortem:: Learning from past difficulties. 63 64Using libtool 65 66* Creating object files:: Compiling object files for libraries. 67* Linking libraries:: Creating libraries from object files. 68* Linking executables:: Linking object files against libtool libraries. 69* Debugging executables:: Running GDB on libtool-generated programs. 70* Installing libraries:: Making libraries available to users. 71* Installing executables:: Making programs available to users. 72* Static libraries:: When shared libraries are not wanted. 73 74Invoking `libtool' 75 76* Compile mode:: Creating library object files. 77* Link mode:: Generating executables and libraries. 78* Execute mode:: Debugging libtool-generated programs. 79* Install mode:: Making libraries and executables public. 80* Finish mode:: Completing a library installation. 81* Uninstall mode:: Removing installed executables and libraries. 82* Clean mode:: Removing uninstalled executables and libraries. 83 84Integrating libtool with your package 85 86* Makefile rules:: Writing `Makefile' rules for libtool. 87* Using Automake:: Automatically supporting libtool. 88* Configuring:: Configuring libtool for a host system. 89* Distributing:: What files to distribute with your package. 90* Static-only libraries:: Sometimes shared libraries are just a pain. 91 92Configuring libtool 93 94* AC_PROG_LIBTOOL:: Configuring `libtool' in `configure.in'. 95 96Including libtool in your package 97 98* Invoking libtoolize:: `libtoolize' command line options. 99* Autoconf .o macros:: Autoconf macros that set object file names. 100 101Library interface versions 102 103* Interfaces:: What are library interfaces? 104* Libtool versioning:: Libtool's versioning system. 105* Updating version info:: Changing version information before releases. 106* Release numbers:: Breaking binary compatibility for aesthetics. 107 108Tips for interface design 109 110* C header files:: How to write portable include files. 111 112Dlopened modules 113 114* Building modules:: Creating dlopenable objects and libraries. 115* Dlpreopening:: Dlopening that works on static platforms. 116* Finding the dlname:: Choosing the right file to `dlopen'. 117* Dlopen issues:: Unresolved problems that need your attention. 118 119Using libltdl 120 121* Libltdl interface:: How to use libltdl in your programs. 122* Modules for libltdl:: Creating modules that can be `dlopen'ed. 123* Thread Safety in libltdl:: Registering callbacks for multi-thread safety. 124* User defined module data:: Associating data with loaded modules. 125* Module loaders for libltdl:: Creating user defined module loaders. 126* Distributing libltdl:: How to distribute libltdl with your package. 127 128Using libtool with other languages 129 130* C++ libraries:: 131 132Troubleshooting 133 134* Libtool test suite:: Libtool's self-tests. 135* Reporting bugs:: How to report problems with libtool. 136 137The libtool test suite 138 139* Test descriptions:: The contents of the test suite. 140* When tests fail:: What to do when a test fails. 141 142Maintenance notes for libtool 143 144* New ports:: How to port libtool to new systems. 145* Tested platforms:: When libtool was last tested. 146* Platform quirks:: Information about different library systems. 147* libtool script contents:: Configuration information that libtool uses. 148* Cheap tricks:: Making libtool maintainership easier. 149 150Porting libtool to new systems 151 152* Information sources:: Where to find relevant documentation 153* Porting inter-library dependencies:: Implementation details explained 154 155Platform quirks 156 157* References:: Finding more information. 158* Compilers:: Creating object files from source files. 159* Reloadable objects:: Binding object files together. 160* Multiple dependencies:: Removing duplicate dependent libraries. 161* Archivers:: Programs that create static archives. 162 163 164File: libtool.info, Node: Introduction, Next: Libtool paradigm, Prev: Top, Up: Top 165 1661 Introduction 167************** 168 169In the past, if a source code package developer wanted to take advantage 170of the power of shared libraries, he needed to write custom support code 171for each platform on which his package ran. He also had to design a 172configuration interface so that the package installer could choose what 173sort of libraries were built. 174 175 GNU Libtool simplifies the developer's job by encapsulating both the 176platform-specific dependencies, and the user interface, in a single 177script. GNU Libtool is designed so that the complete functionality of 178each host type is available via a generic interface, but nasty quirks 179are hidden from the programmer. 180 181 GNU Libtool's consistent interface is reassuring... users don't need 182to read obscure documentation in order to have their favorite source 183package build shared libraries. They just run your package `configure' 184script (or equivalent), and libtool does all the dirty work. 185 186 There are several examples throughout this document. All assume the 187same environment: we want to build a library, `libhello', in a generic 188way. 189 190 `libhello' could be a shared library, a static library, or both... 191whatever is available on the host system, as long as libtool has been 192ported to it. 193 194 This chapter explains the original design philosophy of libtool. 195Feel free to skip to the next chapter, unless you are interested in 196history, or want to write code to extend libtool in a consistent way. 197 198* Menu: 199 200* Motivation:: Why does GNU need a libtool? 201* Issues:: The problems that need to be addressed. 202* Other implementations:: How other people have solved these issues. 203* Postmortem:: Learning from past difficulties. 204 205 206File: libtool.info, Node: Motivation, Next: Issues, Up: Introduction 207 2081.1 Motivation for writing libtool 209================================== 210 211Since early 1995, several different GNU developers have recognized the 212importance of having shared library support for their packages. The 213primary motivation for such a change is to encourage modularity and 214reuse of code (both conceptually and physically) in GNU programs. 215 216 Such a demand means that the way libraries are built in GNU packages 217needs to be general, to allow for any library type the package installer 218might want. The problem is compounded by the absence of a standard 219procedure for creating shared libraries on different platforms. 220 221 The following sections outline the major issues facing shared library 222support in GNU, and how shared library support could be standardized 223with libtool. 224 225 The following specifications were used in developing and evaluating 226this system: 227 228 1. The system must be as elegant as possible. 229 230 2. The system must be fully integrated with the GNU Autoconf and 231 Automake utilities, so that it will be easy for GNU maintainers to 232 use. However, the system must not require these tools, so that it 233 can be used by non-GNU packages. 234 235 3. Portability to other (non-GNU) architectures and tools is 236 desirable. 237 238 239File: libtool.info, Node: Issues, Next: Other implementations, Prev: Motivation, Up: Introduction 240 2411.2 Implementation issues 242========================= 243 244The following issues need to be addressed in any reusable shared library 245system, specifically libtool: 246 247 1. The package installer should be able to control what sort of 248 libraries are built. 249 250 2. It can be tricky to run dynamically linked programs whose 251 libraries have not yet been installed. `LD_LIBRARY_PATH' must be 252 set properly (if it is supported), or programs fail to run. 253 254 3. The system must operate consistently even on hosts which don't 255 support shared libraries. 256 257 4. The commands required to build shared libraries may differ wildly 258 from host to host. These need to be determined at configure time 259 in a consistent way. 260 261 5. It is not always obvious with which suffix a shared library should 262 be installed. This makes it difficult for `Makefile' rules, since 263 they generally assume that file names are the same from host to 264 host. 265 266 6. The system needs a simple library version number abstraction, so 267 that shared libraries can be upgraded in place. The programmer 268 should be informed how to design the interfaces to the library to 269 maximize binary compatibility. 270 271 7. The install `Makefile' target should warn the package installer to 272 set the proper environment variables (`LD_LIBRARY_PATH' or 273 equivalent), or run `ldconfig'. 274 275 276File: libtool.info, Node: Other implementations, Next: Postmortem, Prev: Issues, Up: Introduction 277 2781.3 Other implementations 279========================= 280 281Even before libtool was developed, many free software packages built and 282installed their own shared libraries. At first, these packages were 283examined to avoid reinventing existing features. 284 285 Now it is clear that none of these packages have documented the 286details of shared library systems that libtool requires. So, other 287packages have been more or less abandoned as influences. 288 289 290File: libtool.info, Node: Postmortem, Prev: Other implementations, Up: Introduction 291 2921.4 A postmortem analysis of other implementations 293================================================== 294 295In all fairness, each of the implementations that were examined do the 296job that they were intended to do, for a number of different host 297systems. However, none of these solutions seem to function well as a 298generalized, reusable component. 299 300 Most were too complex to use (much less modify) without understanding 301exactly what the implementation does, and they were generally not 302documented. 303 304 The main difficulty is that different vendors have different views of 305what libraries are, and none of the packages which were examined seemed 306to be confident enough to settle on a single paradigm that just _works_. 307 308 Ideally, libtool would be a standard that would be implemented as 309series of extensions and modifications to existing library systems to 310make them work consistently. However, it is not an easy task to 311convince operating system developers to mend their evil ways, and 312people want to build shared libraries right now, even on buggy, broken, 313confused operating systems. 314 315 For this reason, libtool was designed as an independent shell script. 316It isolates the problems and inconsistencies in library building that 317plague `Makefile' writers by wrapping the compiler suite on different 318platforms with a consistent, powerful interface. 319 320 With luck, libtool will be useful to and used by the GNU community, 321and that the lessons that were learned in writing it will be taken up by 322designers of future library systems. 323 324 325File: libtool.info, Node: Libtool paradigm, Next: Using libtool, Prev: Introduction, Up: Top 326 3272 The libtool paradigm 328********************** 329 330At first, libtool was designed to support an arbitrary number of library 331object types. After libtool was ported to more platforms, a new 332paradigm gradually developed for describing the relationship between 333libraries and programs. 334 335 In summary, "libraries are programs with multiple entry points, and 336more formally defined interfaces." 337 338 Version 0.7 of libtool was a complete redesign and rewrite of 339libtool to reflect this new paradigm. So far, it has proved to be 340successful: libtool is simpler and more useful than before. 341 342 The best way to introduce the libtool paradigm is to contrast it with 343the paradigm of existing library systems, with examples from each. It 344is a new way of thinking, so it may take a little time to absorb, but 345when you understand it, the world becomes simpler. 346 347 348File: libtool.info, Node: Using libtool, Next: Invoking libtool, Prev: Libtool paradigm, Up: Top 349 3503 Using libtool 351*************** 352 353It makes little sense to talk about using libtool in your own packages 354until you have seen how it makes your life simpler. The examples in 355this chapter introduce the main features of libtool by comparing the 356standard library building procedure to libtool's operation on two 357different platforms: 358 359`a23' 360 An Ultrix 4.2 platform with only static libraries. 361 362`burger' 363 A NetBSD/i386 1.2 platform with shared libraries. 364 365 You can follow these examples on your own platform, using the 366preconfigured libtool script that was installed with libtool (*note 367Configuring::). 368 369 Source files for the following examples are taken from the `demo' 370subdirectory of the libtool distribution. Assume that we are building a 371library, `libhello', out of the files `foo.c' and `hello.c'. 372 373 Note that the `foo.c' source file uses the `cos' math library 374function, which is usually found in the standalone math library, and not 375the C library (*note Trigonometric Functions: (libc)Trig Functions.). 376So, we need to add `-lm' to the end of the link line whenever we link 377`foo.o' or `foo.lo' into an executable or a library (*note 378Inter-library dependencies::). 379 380 The same rule applies whenever you use functions that don't appear in 381the standard C library... you need to add the appropriate `-lNAME' flag 382to the end of the link line when you link against those objects. 383 384 After we have built that library, we want to create a program by 385linking `main.o' against `libhello'. 386 387* Menu: 388 389* Creating object files:: Compiling object files for libraries. 390* Linking libraries:: Creating libraries from object files. 391* Linking executables:: Linking object files against libtool libraries. 392* Debugging executables:: Running GDB on libtool-generated programs. 393* Installing libraries:: Making libraries available to users. 394* Installing executables:: Making programs available to users. 395* Static libraries:: When shared libraries are not wanted. 396 397 398File: libtool.info, Node: Creating object files, Next: Linking libraries, Up: Using libtool 399 4003.1 Creating object files 401========================= 402 403To create an object file from a source file, the compiler is invoked 404with the `-c' flag (and any other desired flags): 405 406 burger$ gcc -g -O -c main.c 407 burger$ 408 409 The above compiler command produces an object file, `main.o', from 410the source file `main.c'. 411 412 For most library systems, creating object files that become part of a 413static library is as simple as creating object files that are linked to 414form an executable: 415 416 burger$ gcc -g -O -c foo.c 417 burger$ gcc -g -O -c hello.c 418 burger$ 419 420 Shared libraries, however, may only be built from 421"position-independent code" (PIC). So, special flags must be passed to 422the compiler to tell it to generate PIC rather than the standard 423position-dependent code. 424 425 Since this is a library implementation detail, libtool hides the 426complexity of PIC compiler flags by using separate library object files 427(which end in `.lo' instead of `.o'). On systems without shared 428libraries (or without special PIC compiler flags), these library object 429files are identical to "standard" object files. 430 431 To create library object files for `foo.c' and `hello.c', simply 432invoke libtool with the standard compilation command as arguments 433(*note Compile mode::): 434 435 a23$ libtool --mode=compile gcc -g -O -c foo.c 436 gcc -g -O -c foo.c 437 echo timestamp > foo.lo 438 a23$ libtool --mode=compile gcc -g -O -c hello.c 439 gcc -g -O -c hello.c 440 echo timestamp > hello.lo 441 a23$ 442 443 Note that libtool creates two files for each invocation. The `.lo' 444file is a library object, which may be built into a shared library, and 445the `.o' file is a standard object file. On `a23', the library objects 446are just timestamps, because only static libraries are supported. 447 448 On shared library systems, libtool automatically inserts the PIC 449generation flags into the compilation command, so that the library 450object and the standard object differ: 451 452 burger$ libtool --mode=compile gcc -g -O -c foo.c 453 gcc -g -O -c -fPIC -DPIC foo.c 454 mv -f foo.o foo.lo 455 gcc -g -O -c foo.c >/dev/null 2>&1 456 burger$ libtool --mode=compile gcc -g -O -c hello.c 457 gcc -g -O -c -fPIC -DPIC hello.c 458 mv -f hello.o hello.lo 459 gcc -g -O -c hello.c >/dev/null 2>&1 460 burger$ 461 462 Notice that the second run of GCC has its output discarded. This is 463done so that compiler warnings aren't annoyingly duplicated. 464 465 466File: libtool.info, Node: Linking libraries, Next: Linking executables, Prev: Creating object files, Up: Using libtool 467 4683.2 Linking libraries 469===================== 470 471Without libtool, the programmer would invoke the `ar' command to create 472a static library: 473 474 burger$ ar cru libhello.a hello.o foo.o 475 burger$ 476 477 But of course, that would be too simple, so many systems require that 478you run the `ranlib' command on the resulting library (to give it 479better karma, or something): 480 481 burger$ ranlib libhello.a 482 burger$ 483 484 It seems more natural to use the C compiler for this task, given 485libtool's "libraries are programs" approach. So, on platforms without 486shared libraries, libtool simply acts as a wrapper for the system `ar' 487(and possibly `ranlib') commands. 488 489 Again, the libtool library name differs from the standard name (it 490has a `.la' suffix instead of a `.a' suffix). The arguments to libtool 491are the same ones you would use to produce an executable named 492`libhello.la' with your compiler (*note Link mode::): 493 494 a23$ libtool --mode=link gcc -g -O -o libhello.la foo.o hello.o 495 libtool: cannot build libtool library `libhello.la' from non-libtool \ 496 objects 497 a23$ 498 499 Aha! Libtool caught a common error... trying to build a library 500from standard objects instead of library objects. This doesn't matter 501for static libraries, but on shared library systems, it is of great 502importance. 503 504 So, let's try again, this time with the library object files. 505Remember also that we need to add `-lm' to the link command line because 506`foo.c' uses the `cos' math library function (*note Using libtool::). 507 508 Another complication in building shared libraries is that we need to 509specify the path to the directory in which they (eventually) will be 510installed (in this case, `/usr/local/lib')(1): 511 512 a23$ libtool --mode=link gcc -g -O -o libhello.la foo.lo hello.lo \ 513 -rpath /usr/local/lib -lm 514 mkdir .libs 515 ar cru .libs/libhello.a foo.o hello.o 516 ranlib .libs/libhello.a 517 creating libhello.la 518 a23$ 519 520 Now, let's try the same trick on the shared library platform: 521 522 burger$ libtool --mode=link gcc -g -O -o libhello.la foo.lo hello.lo \ 523 -rpath /usr/local/lib -lm 524 mkdir .libs 525 ld -Bshareable -o .libs/libhello.so.0.0 foo.lo hello.lo -lm 526 ar cru .libs/libhello.a foo.o hello.o 527 ranlib .libs/libhello.a 528 creating libhello.la 529 burger$ 530 531 Now that's significantly cooler... libtool just ran an obscure `ld' 532command to create a shared library, as well as the static library. 533 534 Note how libtool creates extra files in the `.libs' subdirectory, 535rather than the current directory. This feature is to make it easier 536to clean up the build directory, and to help ensure that other programs 537fail horribly if you accidentally forget to use libtool when you should. 538 539 ---------- Footnotes ---------- 540 541 (1) If you don't specify an `rpath', then libtool builds a libtool 542convenience archive, not a shared library (*note Static libraries::). 543 544 545File: libtool.info, Node: Linking executables, Next: Debugging executables, Prev: Linking libraries, Up: Using libtool 546 5473.3 Linking executables 548======================= 549 550If you choose at this point to "install" the library (put it in a 551permanent location) before linking executables against it, then you 552don't need to use libtool to do the linking. Simply use the appropriate 553`-L' and `-l' flags to specify the library's location. 554 555 Some system linkers insist on encoding the full directory name of 556each shared library in the resulting executable. Libtool has to work 557around this misfeature by special magic to ensure that only permanent 558directory names are put into installed executables. 559 560 The importance of this bug must not be overlooked: it won't cause 561programs to crash in obvious ways. It creates a security hole, and 562possibly even worse, if you are modifying the library source code after 563you have installed the package, you will change the behaviour of the 564installed programs! 565 566 So, if you want to link programs against the library before you 567install it, you must use libtool to do the linking. 568 569 Here's the old way of linking against an uninstalled library: 570 571 burger$ gcc -g -O -o hell.old main.o libhello.a -lm 572 burger$ 573 574 Libtool's way is almost the same(1) (*note Link mode::): 575 576 a23$ libtool --mode=link gcc -g -O -o hell main.o libhello.la -lm 577 gcc -g -O -o hell main.o ./.libs/libhello.a -lm 578 a23$ 579 580 That looks too simple to be true. All libtool did was transform 581`libhello.la' to `./.libs/libhello.a', but remember that `a23' has no 582shared libraries. 583 584 On `burger' the situation is different: 585 586 burger$ libtool --mode=link gcc -g -O -o hell main.o libhello.la -lm 587 gcc -g -O -o .libs/hell main.o -L./.libs -R/usr/local/lib -lhello -lm 588 creating hell 589 burger$ 590 591 Now assume `libhello.la' had already been installed, and you want to 592link a new program with it. You could figure out where it lives by 593yourself, then run: 594 595 burger$ gcc -g -O -o test test.o -L/usr/local/lib -lhello 596 597 However, unless `/usr/local/lib' is in the standard library search 598path, you won't be able to run `test'. However, if you use libtool to 599link the already-installed libtool library, it will do The Right Thing 600(TM) for you: 601 602 burger$ libtool --mode=link gcc -g -O -o test \ 603 test.o /usr/local/lib/libhello.la 604 gcc -g -O -o .libs/test test.o -Wl,--rpath 605 -Wl,/usr/local/lib /usr/local/lib/libhello.a -lm 606 creating test 607 burger$ 608 609 Note that libtool added the necessary run-time path flag, as well as 610`-lm', the library libhello.la depended upon. Nice, huh? 611 612 Since libtool created a wrapper script, you should use libtool to 613install it and debug it too. However, since the program does not depend 614on any uninstalled libtool library, it is probably usable even without 615the wrapper script. Libtool could probably be made smarter to avoid the 616creation of the wrapper script in this case, but this is left as an 617exercise for the reader. 618 619 Notice that the executable, `hell', was actually created in the 620`.libs' subdirectory. Then, a wrapper script was created in the 621current directory. 622 623 On NetBSD 1.2, libtool encodes the installation directory of 624`libhello', by using the `-R/usr/local/lib' compiler flag. Then, the 625wrapper script guarantees that the executable finds the correct shared 626library (the one in `./.libs') until it is properly installed. 627 628 Let's compare the two different programs: 629 630 burger$ time ./hell.old 631 Welcome to GNU Hell! 632 ** This is not GNU Hello. There is no built-in mail reader. ** 633 0.21 real 0.02 user 0.08 sys 634 burger$ time ./hell 635 Welcome to GNU Hell! 636 ** This is not GNU Hello. There is no built-in mail reader. ** 637 0.63 real 0.09 user 0.59 sys 638 burger$ 639 640 The wrapper script takes significantly longer to execute, but at 641least the results are correct, even though the shared library hasn't 642been installed yet. 643 644 So, what about all the space savings that shared libraries are 645supposed to yield? 646 647 burger$ ls -l hell.old libhello.a 648 -rwxr-xr-x 1 gord gord 15481 Nov 14 12:11 hell.old 649 -rw-r--r-- 1 gord gord 4274 Nov 13 18:02 libhello.a 650 burger$ ls -l .libs/hell .libs/libhello.* 651 -rwxr-xr-x 1 gord gord 11647 Nov 14 12:10 .libs/hell 652 -rw-r--r-- 1 gord gord 4274 Nov 13 18:44 .libs/libhello.a 653 -rwxr-xr-x 1 gord gord 12205 Nov 13 18:44 .libs/libhello.so.0.0 654 burger$ 655 656 Well, that sucks. Maybe I should just scrap this project and take up 657basket weaving. 658 659 Actually, it just proves an important point: shared libraries incur 660overhead because of their (relative) complexity. In this situation, the 661price of being dynamic is eight kilobytes, and the payoff is about four 662kilobytes. So, having a shared `libhello' won't be an advantage until 663we link it against at least a few more programs. 664 665 ---------- Footnotes ---------- 666 667 (1) However, you should avoid using `-L' or `-l' flags to link 668against an uninstalled libtool library. Just specify the relative path 669to the `.la' file, such as `../intl/libintl.la'. This is a design 670decision to eliminate any ambiguity when linking against uninstalled 671shared libraries. 672 673 674File: libtool.info, Node: Debugging executables, Next: Installing libraries, Prev: Linking executables, Up: Using libtool 675 6763.4 Debugging executables 677========================= 678 679If `hell' was a complicated program, you would certainly want to test 680and debug it before installing it on your system. In the above 681section, you saw how the libtool wrapper script makes it possible to run 682the program directly, but unfortunately, this mechanism interferes with 683the debugger: 684 685 burger$ gdb hell 686 GDB is free software and you are welcome to distribute copies of it 687 under certain conditions; type "show copying" to see the conditions. 688 There is no warranty for GDB; type "show warranty" for details. 689 GDB 4.16 (i386-unknown-netbsd), (C) 1996 Free Software Foundation, Inc. 690 691 "hell": not in executable format: File format not recognized 692 693 (gdb) quit 694 burger$ 695 696 Sad. It doesn't work because GDB doesn't know where the executable 697lives. So, let's try again, by invoking GDB directly on the executable: 698 699 burger$ gdb .libs/hell 700 trick:/home/src/libtool/demo$ gdb .libs/hell 701 GDB is free software and you are welcome to distribute copies of it 702 under certain conditions; type "show copying" to see the conditions. 703 There is no warranty for GDB; type "show warranty" for details. 704 GDB 4.16 (i386-unknown-netbsd), (C) 1996 Free Software Foundation, Inc. 705 (gdb) break main 706 Breakpoint 1 at 0x8048547: file main.c, line 29. 707 (gdb) run 708 Starting program: /home/src/libtool/demo/.libs/hell 709 /home/src/libtool/demo/.libs/hell: can't load library 'libhello.so.2' 710 711 Program exited with code 020. 712 (gdb) quit 713 burger$ 714 715 Argh. Now GDB complains because it cannot find the shared library 716that `hell' is linked against. So, we must use libtool in order to 717properly set the library path and run the debugger. Fortunately, we can 718forget all about the `.libs' directory, and just run it on the 719executable wrapper (*note Execute mode::): 720 721 burger$ libtool --mode=execute gdb hell 722 GDB is free software and you are welcome to distribute copies of it 723 under certain conditions; type "show copying" to see the conditions. 724 There is no warranty for GDB; type "show warranty" for details. 725 GDB 4.16 (i386-unknown-netbsd), (C) 1996 Free Software Foundation, Inc. 726 (gdb) break main 727 Breakpoint 1 at 0x8048547: file main.c, line 29. 728 (gdb) run 729 Starting program: /home/src/libtool/demo/.libs/hell 730 731 Breakpoint 1, main (argc=1, argv=0xbffffc40) at main.c:29 732 29 printf ("Welcome to GNU Hell!\n"); 733 (gdb) quit 734 The program is running. Quit anyway (and kill it)? (y or n) y 735 burger$ 736 737 738File: libtool.info, Node: Installing libraries, Next: Installing executables, Prev: Debugging executables, Up: Using libtool 739 7403.5 Installing libraries 741======================== 742 743Installing libraries on a non-libtool system is quite 744straightforward... just copy them into place:(1) 745 746 burger$ su 747 Password: ******** 748 burger# cp libhello.a /usr/local/lib/libhello.a 749 burger# 750 751 Oops, don't forget the `ranlib' command: 752 753 burger# ranlib /usr/local/lib/libhello.a 754 burger# 755 756 Libtool installation is quite simple, as well. Just use the 757`install' or `cp' command that you normally would (*note Install 758mode::): 759 760 a23# libtool --mode=install cp libhello.la /usr/local/lib/libhello.la 761 cp libhello.la /usr/local/lib/libhello.la 762 cp .libs/libhello.a /usr/local/lib/libhello.a 763 ranlib /usr/local/lib/libhello.a 764 a23# 765 766 Note that the libtool library `libhello.la' is also installed, to 767help libtool with uninstallation (*note Uninstall mode::) and linking 768(*note Linking executables::) and to help programs with dlopening 769(*note Dlopened modules::). 770 771 Here is the shared library example: 772 773 burger# libtool --mode=install install -c libhello.la \ 774 /usr/local/lib/libhello.la 775 install -c .libs/libhello.so.0.0 /usr/local/lib/libhello.so.0.0 776 install -c libhello.la /usr/local/lib/libhello.la 777 install -c .libs/libhello.a /usr/local/lib/libhello.a 778 ranlib /usr/local/lib/libhello.a 779 burger# 780 781 It is safe to specify the `-s' (strip symbols) flag if you use a 782BSD-compatible install program when installing libraries. Libtool will 783either ignore the `-s' flag, or will run a program that will strip only 784debugging and compiler symbols from the library. 785 786 Once the libraries have been put in place, there may be some 787additional configuration that you need to do before using them. First, 788you must make sure that where the library is installed actually agrees 789with the `-rpath' flag you used to build it. 790 791 Then, running `libtool -n --mode=finish LIBDIR' can give you further 792hints on what to do (*note Finish mode::): 793 794 burger# libtool -n --mode=finish /usr/local/lib 795 PATH="$PATH:/sbin" ldconfig -m /usr/local/lib 796 ----------------------------------------------------------------- 797 Libraries have been installed in: 798 /usr/local/lib 799 800 To link against installed libraries in a given directory, LIBDIR, 801 you must use the `-LLIBDIR' flag during linking. 802 803 You will also need to do one of the following: 804 - add LIBDIR to the `LD_LIBRARY_PATH' environment variable 805 during execution 806 - add LIBDIR to the `LD_RUN_PATH' environment variable 807 during linking 808 - use the `-RLIBDIR' linker flag 809 810 See any operating system documentation about shared libraries for 811 more information, such as the ld and ld.so manual pages. 812 ----------------------------------------------------------------- 813 burger# 814 815 After you have completed these steps, you can go on to begin using 816the installed libraries. You may also install any executables that 817depend on libraries you created. 818 819 ---------- Footnotes ---------- 820 821 (1) Don't accidentally strip the libraries, though, or they will be 822unusable. 823 824 825File: libtool.info, Node: Installing executables, Next: Static libraries, Prev: Installing libraries, Up: Using libtool 826 8273.6 Installing executables 828========================== 829 830If you used libtool to link any executables against uninstalled libtool 831libraries (*note Linking executables::), you need to use libtool to 832install the executables after the libraries have been installed (*note 833Installing libraries::). 834 835 So, for our Ultrix example, we would run: 836 837 a23# libtool install -c hell /usr/local/bin/hell 838 install -c hell /usr/local/bin/hell 839 a23# 840 841 On shared library systems, libtool just ignores the wrapper script 842and installs the correct binary: 843 844 burger# libtool install -c hell /usr/local/bin/hell 845 install -c .libs/hell /usr/local/bin/hell 846 burger# 847 848 849File: libtool.info, Node: Static libraries, Prev: Installing executables, Up: Using libtool 850 8513.7 Linking static libraries 852============================ 853 854Why return to `ar' and `ranlib' silliness when you've had a taste of 855libtool? Well, sometimes it is desirable to create a static archive 856that can never be shared. The most frequent case is when you have a 857set of object files that you use to build several different programs. 858You can create a "convenience library" out of those objects, and link 859programs with the library, instead of listing all object files for 860every program. This technique is often used to overcome GNU automake's 861lack of support for linking object files built from sources in other 862directories, because it supports linking with libraries from other 863directories. This limitation applies to GNU automake up to release 8641.4; newer releases should support sources in other directories. 865 866 If you just want to link this convenience library into programs, then 867you could just ignore libtool entirely, and use the old `ar' and 868`ranlib' commands (or the corresponding GNU automake `_LIBRARIES' 869rules). You can even install a convenience library (but you probably 870don't want to) using libtool: 871 872 burger$ libtool --mode=install ./install-sh -c libhello.a \ 873 /local/lib/libhello.a 874 ./install-sh -c libhello.a /local/lib/libhello.a 875 ranlib /local/lib/libhello.a 876 burger$ 877 878 Using libtool for static library installation protects your library 879from being accidentally stripped (if the installer used the `-s' flag), 880as well as automatically running the correct `ranlib' command. 881 882 But libtool libraries are more than just collections of object files: 883they can also carry library dependency information, which old archives 884do not. If you want to create a libtool static convenience library, you 885can omit the `-rpath' flag and use `-static' to indicate that you're 886only interested in a static library. When you link a program with such 887a library, libtool will actually link all object files and dependency 888libraries into the program. 889 890 If you omit both `-rpath' and `-static', libtool will create a 891convenience library that can be used to create other libtool libraries, 892even shared ones. Just like in the static case, the library behaves as 893an alias to a set of object files and dependency libraries, but in this 894case the object files are suitable for inclusion in shared libraries. 895But be careful not to link a single convenience library, directly or 896indirectly, into a single program or library, otherwise you may get 897errors about symbol redefinitions. 898 899 When GNU automake is used, you should use `noinst_LTLIBRARIES' 900instead of `lib_LTLIBRARIES' for convenience libraries, so that the 901`-rpath' option is not passed when they are linked. 902 903 As a rule of thumb, link a libtool convenience library into at most 904one libtool library, and never into a program, and link libtool static 905convenience libraries only into programs, and only if you need to carry 906library dependency information to the user of the static convenience 907library. 908 909 Another common situation where static linking is desirable is in 910creating a standalone binary. Use libtool to do the linking and add the 911`-all-static' flag. 912 913 914File: libtool.info, Node: Invoking libtool, Next: Integrating libtool, Prev: Using libtool, Up: Top 915 9164 Invoking `libtool' 917******************** 918 919The `libtool' program has the following synopsis: 920 921 libtool [OPTION]... [MODE-ARG]... 922 923and accepts the following options: 924 925`--config' 926 Display libtool configuration variables and exit. 927 928`--debug' 929 Dump a trace of shell script execution to standard output. This 930 produces a lot of output, so you may wish to pipe it to `less' (or 931 `more') or redirect to a file. 932 933`-n' 934`--dry-run' 935 Don't create, modify, or delete any files, just show what commands 936 would be executed by libtool. 937 938`--features' 939 Display basic configuration options. This provides a way for 940 packages to determine whether shared or static libraries will be 941 built. 942 943`--preserve-dup-deps' 944 Do not remove duplicate dependencies in libraries. When building 945 packages with static libraries, the libraries may depend 946 circularly on each other (shared libs can too, but for those it 947 doesn't matter), so there are situations, where -la -lb -la is 948 required, and the second -la may not be stripped or the link will 949 fail. In cases where these duplications are required, this option 950 will preserve them, only stripping the libraries that libtool 951 knows it can safely. 952 953`--finish' 954 Same as `--mode=finish'. 955 956`--help' 957 Display a help message and exit. If `--mode=MODE' is specified, 958 then detailed help for MODE is displayed. 959 960`--mode=MODE' 961 Use MODE as the operation mode. If not specified, an attempt is 962 made to inferr the operation mode from the MODE-ARGS. Not 963 specifying the MODE is currently deprecated, as there are too many 964 situations where it is not possible to guess. Future versions of 965 Libtool will require that MODE be explicity set. 966 967 MODE must be set to one of the following: 968 969 `compile' 970 Compile a source file into a libtool object. 971 972 `execute' 973 Automatically set the library path so that another program 974 can use uninstalled libtool-generated programs or libraries. 975 976 `finish' 977 Complete the installation of libtool libraries on the system. 978 979 `install' 980 Install libraries or executables. 981 982 `link' 983 Create a library or an executable. 984 985 `uninstall' 986 Delete installed libraries or executables. 987 988 `clean' 989 Delete uninstalled libraries or executables. 990 991`--version' 992 Print libtool version information and exit. 993 994 The MODE-ARGS are a variable number of arguments, depending on the 995selected operation mode. In general, each MODE-ARG is interpreted by 996programs libtool invokes, rather than libtool itself. 997 998* Menu: 999 1000* Compile mode:: Creating library object files. 1001* Link mode:: Generating executables and libraries. 1002* Execute mode:: Debugging libtool-generated programs. 1003* Install mode:: Making libraries and executables public. 1004* Finish mode:: Completing a library installation. 1005* Uninstall mode:: Removing installed executables and libraries. 1006* Clean mode:: Removing uninstalled executables and libraries. 1007 1008 1009File: libtool.info, Node: Compile mode, Next: Link mode, Up: Invoking libtool 1010 10114.1 Compile mode 1012================ 1013 1014For "compile" mode, MODE-ARGS is a compiler command to be used in 1015creating a `standard' object file. These arguments should begin with 1016the name of the C compiler, and contain the `-c' compiler flag so that 1017only an object file is created. 1018 1019 Libtool determines the name of the output file by removing the 1020directory component from the source file name, then substituting the 1021source code suffix (e.g. `.c' for C source code) with the library 1022object suffix, `.lo'. 1023 1024 If shared libraries are being built, any necessary PIC generation 1025flags are substituted into the compilation command. You can pass link 1026specific flags to the compiler driver using `-XCClinker FLAG' or pass 1027linker flags with `-Wl,FLAG' and `-Xlinker FLAG'. You can also pass 1028compile specific flags using `-Wc,FLAG' and `-Xcompiler FLAG'. 1029 1030 If both PIC and non-PIC objects are being built, libtool will 1031normally supress the compiler output for the PIC object compilation to 1032save showing very similar, if not identical duplicate output for each 1033object. If the `-no-suppress' option is given in compile mode, libtool 1034will show the compiler output for both objects. 1035 1036 If the `-static' option is given, then a `.o' file is built, even if 1037libtool was configured with `--disable-static'. 1038 1039 Note that the `-o' option is now fully supported. It is emulated on 1040the platforms that don't support it (by locking and moving the 1041objects), so it is really easy to use libtool, just with minor 1042modifications to your Makefiles. Typing for example 1043 libtool gcc -c foo/x.c -o foo/x.lo 1044 will do what you expect. 1045 1046 Note, however, that, if the compiler does not support `-c' and `-o', 1047it is impossible to compile `foo/x.c' without overwriting an existing 1048`./x.o'. Therefore, if you do have a source file `./x.c', make sure 1049you introduce dependencies in your `Makefile' to make sure `./x.o' (or 1050`./x.lo') is re-created after any sub-directory's `x.lo': 1051 x.o x.lo: foo/x.lo bar/x.lo 1052 This will also ensure that make won't try to use a temporarily 1053corrupted `x.o' to create a program or library. It may cause needless 1054recompilation on platforms that support `-c' and `-o' together, but 1055it's the only way to make it safe for those that don't. 1056 1057 1058File: libtool.info, Node: Link mode, Next: Execute mode, Prev: Compile mode, Up: Invoking libtool 1059 10604.2 Link mode 1061============= 1062 1063"Link" mode links together object files (including library objects) to 1064form another library or to create an executable program. 1065 1066 MODE-ARGS consist of a command using the C compiler to create an 1067output file (with the `-o' flag) from several object files. 1068 1069 The following components of MODE-ARGS are treated specially: 1070 1071`-all-static' 1072 If OUTPUT-FILE is a program, then do not link it against any 1073 shared libraries at all. If OUTPUT-FILE is a library, then only 1074 create a static library. 1075 1076`-avoid-version' 1077 Tries to avoid versioning (*note Versioning::) for libraries and 1078 modules, i.e. no version information is stored and no symbolic 1079 links are created. If the platform requires versioning, this 1080 option has no effect. 1081 1082`-dlopen FILE' 1083 Same as `-dlpreopen FILE', if native dlopening is not supported on 1084 the host platform (*note Dlopened modules::) or if the program is 1085 linked with `-static' or `-all-static'. Otherwise, no effect. If 1086 FILE is `self' libtool will make sure that the program can 1087 `dlopen' itself, either by enabling `-export-dynamic' or by 1088 falling back to `-dlpreopen self'. 1089 1090`-dlpreopen FILE' 1091 Link FILE into the output program, and add its symbols to 1092 LT_PRELOADED_SYMBOLS (*note Dlpreopening::). If FILE is `self', 1093 the symbols of the program itself will be added to 1094 LT_PRELOADED_SYMBOLS. If FILE is `force' libtool will make sure 1095 that LT_PRELOADED_SYMBOLS is always _defined_, regardless of 1096 whether it's empty or not. 1097 1098`-export-dynamic' 1099 Allow symbols from OUTPUT-FILE to be resolved with `dlsym' (*note 1100 Dlopened modules::). 1101 1102`-export-symbols SYMFILE' 1103 Tells the linker to export only the symbols listed in SYMFILE. 1104 The symbol file should end in `.sym' and must contain the name of 1105 one symbol per line. This option has no effect on some platforms. 1106 By default all symbols are exported. 1107 1108`-export-symbols-regex REGEX' 1109 Same as `-export-symbols', except that only symbols matching the 1110 regular expression REGEX are exported. By default all symbols are 1111 exported. 1112 1113`-LLIBDIR' 1114 Search LIBDIR for required libraries that have already been 1115 installed. 1116 1117`-lNAME' 1118 OUTPUT-FILE requires the installed library `libNAME'. This option 1119 is required even when OUTPUT-FILE is not an executable. 1120 1121`-module' 1122 Creates a library that can be dlopened (*note Dlopened modules::). 1123 This option doesn't work for programs. Module names don't need to 1124 be prefixed with 'lib'. In order to prevent name clashes, 1125 however, 'libname' and 'name' must not be used at the same time in 1126 your package. 1127 1128`-no-fast-install' 1129 Disable fast-install mode for the executable OUTPUT-FILE. Useful 1130 if the program won't be necessarily installed. 1131 1132`-no-install' 1133 Link an executable OUTPUT-FILE that can't be installed and 1134 therefore doesn't need a wrapper script. Useful if the program is 1135 only used in the build tree, e.g., for testing or generating other 1136 files. 1137 1138`-no-undefined' 1139 Declare that OUTPUT-FILE does not depend on any other libraries. 1140 Some platforms cannot create shared libraries that depend on other 1141 libraries (*note Inter-library dependencies::). 1142 1143`-o OUTPUT-FILE' 1144 Create OUTPUT-FILE from the specified objects and libraries. 1145 1146`-objectlist FILE' 1147 Use a list of object files found in FILE to specify objects. 1148 1149`-precious-files-regex REGEX' 1150 Prevents removal of files from the temporary output directory whose 1151 names match this regular expression. You might specify `\.bbg?$' 1152 to keep those files created with `gcc -ftest-coverage' for example. 1153 1154`-release RELEASE' 1155 Specify that the library was generated by release RELEASE of your 1156 package, so that users can easily tell which versions are newer 1157 than others. Be warned that no two releases of your package will 1158 be binary compatible if you use this flag. If you want binary 1159 compatibility, use the `-version-info' flag instead (*note 1160 Versioning::). 1161 1162`-rpath LIBDIR' 1163 If OUTPUT-FILE is a library, it will eventually be installed in 1164 LIBDIR. If OUTPUT-FILE is a program, add LIBDIR to the run-time 1165 path of the program. 1166 1167`-shrext SUFFIX' 1168 If OUTPUT-FILE is a libtool library, replace the system's standard 1169 file name extension for shared libraries with SUFFIX (most systems 1170 use `.so' here). This option is helpful in certain cases where an 1171 application requires that shared libraries (typically modules) 1172 have an extension other than the default one. Please note you 1173 must supply the full file name extension including any leading dot. 1174 1175`-R LIBDIR' 1176 If OUTPUT-FILE is a program, add LIBDIR to its run-time path. If 1177 OUTPUT-FILE is a library, add -RLIBDIR to its DEPENDENCY_LIBS, so 1178 that, whenever the library is linked into a program, LIBDIR will 1179 be added to its run-time path. 1180 1181`-static' 1182 If OUTPUT-FILE is a program, then do not link it against any 1183 uninstalled shared libtool libraries. If OUTPUT-FILE is a 1184 library, then only create a static library. 1185 1186`-version-info CURRENT[:REVISION[:AGE]]' 1187 If OUTPUT-FILE is a libtool library, use interface version 1188 information CURRENT, REVISION, and AGE to build it (*note 1189 Versioning::). Do *not* use this flag to specify package release 1190 information, rather see the `-release' flag. 1191 1192`-version-number MAJOR[:MINOR[:REVISION]]' 1193 If OUTPUT-FILE is a libtool library, compute interface version 1194 information so that the resulting library uses the specified 1195 major, minor and revision numbers. This is designed to permit 1196 libtool to be used with existing projects where identical version 1197 numbers are already used across operating systems. New projects 1198 should use the `-version-info' flag instead. 1199 1200`-Wl,FLAG' 1201`-Xlinker FLAG' 1202 Pass a linker specific flag directly to the linker. 1203 1204`-XCClinker FLAG' 1205 Pass a link specific flag to the compiler driver (CC) during 1206 linking. 1207 1208 If the OUTPUT-FILE ends in `.la', then a libtool library is created, 1209which must be built only from library objects (`.lo' files). The 1210`-rpath' option is required. In the current implementation, libtool 1211libraries may not depend on other uninstalled libtool libraries (*note 1212Inter-library dependencies::). 1213 1214 If the OUTPUT-FILE ends in `.a', then a standard library is created 1215using `ar' and possibly `ranlib'. 1216 1217 If OUTPUT-FILE ends in `.o' or `.lo', then a reloadable object file 1218is created from the input files (generally using `ld -r'). This method 1219is often called "partial linking". 1220 1221 Otherwise, an executable program is created. 1222 1223 1224File: libtool.info, Node: Execute mode, Next: Install mode, Prev: Link mode, Up: Invoking libtool 1225 12264.3 Execute mode 1227================ 1228 1229For "execute" mode, the library path is automatically set, then a 1230program is executed. 1231 1232 The first of the MODE-ARGS is treated as a program name, with the 1233rest as arguments to that program. 1234 1235 The following components of MODE-ARGS are treated specially: 1236 1237`-dlopen FILE' 1238 Add the directory containing FILE to the library path. 1239 1240 This mode sets the library path environment variable according to any 1241`-dlopen' flags. 1242 1243 If any of the ARGS are libtool executable wrappers, then they are 1244translated into the name of their corresponding uninstalled binary, and 1245any of their required library directories are added to the library path. 1246 1247 1248File: libtool.info, Node: Install mode, Next: Finish mode, Prev: Execute mode, Up: Invoking libtool 1249 12504.4 Install mode 1251================ 1252 1253In "install" mode, libtool interprets most of the elements of MODE-ARGS 1254as an installation command beginning with `cp', or a BSD-compatible 1255`install' program. 1256 1257 The following components of MODE-ARGS are treated specially: 1258 1259`-inst-prefix INST-PREFIX-DIR' 1260 When installing into a temporary staging area, rather than the 1261 final PREFIX, this argument is used to reflect the temporary path, 1262 in much the same way `automake' uses DESTDIR. For instance, if 1263 PREFIX is `/usr/local', but INST-PREFIX-DIR is `/tmp', then the 1264 object will be installed under `/tmp/usr/local/'. If the 1265 installed object is a libtool library, then the internal fields of 1266 that library will reflect only PREFIX, not INST-PREFIX-DIR: 1267 1268 # Directory that this library needs to be installed in: 1269 libdir='/usr/local/lib' 1270 1271 not 1272 1273 # Directory that this library needs to be installed in: 1274 libdir='/tmp/usr/local/lib' 1275 1276 `inst-prefix' is also used to insure that if the installed object 1277 must be relinked upon installation, that it is relinked against 1278 the libraries in INST-PREFIX-DIR/PREFIX, not PREFIX. 1279 1280 In truth, this option is not really intended for use when calling 1281 libtool directly; it is automatically used when `libtool 1282 --mode=install' calls `libtool --mode=relink'. Libtool does this 1283 by analyzing the destination path given in the original `libtool 1284 --mode=install' command and comparing it to the expected 1285 installation path established during `libtool --mode=link'. 1286 1287 Thus, end-users need change nothing, and `automake'-style `make 1288 install DESTDIR=/tmp' will Just Work(tm). 1289 1290 The rest of the MODE-ARGS are interpreted as arguments to the `cp' 1291or `install' command. 1292 1293 The command is run, and any necessary unprivileged post-installation 1294commands are also completed. 1295 1296 1297File: libtool.info, Node: Finish mode, Next: Uninstall mode, Prev: Install mode, Up: Invoking libtool 1298 12994.5 Finish mode 1300=============== 1301 1302"Finish" mode helps system administrators install libtool libraries so 1303that they can be located and linked into user programs. 1304 1305 Each MODE-ARG is interpreted as the name of a library directory. 1306Running this command may require superuser privileges, so the 1307`--dry-run' option may be useful. 1308 1309 1310File: libtool.info, Node: Uninstall mode, Next: Clean mode, Prev: Finish mode, Up: Invoking libtool 1311 13124.6 Uninstall mode 1313================== 1314 1315"Uninstall" mode deletes installed libraries, executables and objects. 1316 1317 The first MODE-ARG is the name of the program to use to delete files 1318(typically `/bin/rm'). 1319 1320 The remaining MODE-ARGS are either flags for the deletion program 1321(beginning with a `-'), or the names of files to delete. 1322 1323 1324File: libtool.info, Node: Clean mode, Prev: Uninstall mode, Up: Invoking libtool 1325 13264.7 Clean mode 1327============== 1328 1329"Clean" mode deletes uninstalled libraries, executables, objects and 1330libtool's temporary files associated with them. 1331 1332 The first MODE-ARG is the name of the program to use to delete files 1333(typically `/bin/rm'). 1334 1335 The remaining MODE-ARGS are either flags for the deletion program 1336(beginning with a `-'), or the names of files to delete. 1337 1338 1339File: libtool.info, Node: Integrating libtool, Next: Versioning, Prev: Invoking libtool, Up: Top 1340 13415 Integrating libtool with your package 1342*************************************** 1343 1344This chapter describes how to integrate libtool with your packages so 1345that your users can install hassle-free shared libraries. 1346 1347* Menu: 1348 1349* Makefile rules:: Writing `Makefile' rules for libtool. 1350* Using Automake:: Automatically supporting libtool. 1351* Configuring:: Configuring libtool for a host system. 1352* Distributing:: What files to distribute with your package. 1353* Static-only libraries:: Sometimes shared libraries are just a pain. 1354 1355 1356File: libtool.info, Node: Makefile rules, Next: Using Automake, Up: Integrating libtool 1357 13585.1 Writing `Makefile' rules for libtool 1359======================================== 1360 1361Libtool is fully integrated with Automake (*note Introduction: 1362(automake)Top.), starting with Automake version 1.2. 1363 1364 If you want to use libtool in a regular `Makefile' (or 1365`Makefile.in'), you are on your own. If you're not using Automake 1.2, 1366and you don't know how to incorporate libtool into your package you 1367need to do one of the following: 1368 1369 1. Download Automake (version 1.2 or later) from your nearest GNU 1370 mirror, install it, and start using it. 1371 1372 2. Learn how to write `Makefile' rules by hand. They're sometimes 1373 complex, but if you're clever enough to write rules for compiling 1374 your old libraries, then you should be able to figure out new 1375 rules for libtool libraries (hint: examine the `Makefile.in' in 1376 the `demo' subdirectory of the libtool distribution... note 1377 especially that it was automatically generated from the 1378 `Makefile.am' by Automake). 1379 1380 1381File: libtool.info, Node: Using Automake, Next: Configuring, Prev: Makefile rules, Up: Integrating libtool 1382 13835.2 Using Automake with libtool 1384=============================== 1385 1386Libtool library support is implemented under the `LTLIBRARIES' primary. 1387 1388 Here are some samples from the Automake `Makefile.am' in the libtool 1389distribution's `demo' subdirectory. 1390 1391 First, to link a program against a libtool library, just use the 1392`program_LDADD' variable: 1393 1394 bin_PROGRAMS = hell hell.debug 1395 1396 # Build hell from main.c and libhello.la 1397 hell_SOURCES = main.c 1398 hell_LDADD = libhello.la 1399 1400 # Create an easier-to-debug version of hell. 1401 hell_debug_SOURCES = main.c 1402 hell_debug_LDADD = libhello.la 1403 hell_debug_LDFLAGS = -static 1404 1405 The flags `-dlopen' or `-dlpreopen' (*note Link mode::) would fit 1406better in the PROGRAM_LDADD variable. Unfortunately, GNU automake, up 1407to release 1.4, doesn't accept these flags in a PROGRAM_LDADD variable, 1408so you have the following alternatives: 1409 1410 * add them to PROGRAM_LDFLAGS, and list the libraries in 1411 PROGRAM_DEPENDENCIES, then wait for a release of GNU automake that 1412 accepts these flags where they belong; 1413 1414 * surround the flags between quotes, but then you must set 1415 PROGRAM_DEPENDENCIES too: 1416 1417 program_LDADD = "-dlopen" libfoo.la 1418 program_DEPENDENCIES = libfoo.la 1419 1420 * set and `AC_SUBST' variables DLOPEN and DLPREOPEN in 1421 `configure.in' and use `@DLOPEN@' and `@DLPREOPEN@' as 1422 replacements for the explicit flags `-dlopen' and `-dlpreopen' in 1423 `program_LDADD'. Automake will discard `AC_SUBST'ed variables 1424 from dependencies, so it will behave exactly as we expect it to 1425 behave when it accepts these flags in `program_LDADD'. But hey!, 1426 this is ugly! 1427 1428 You may use the `program_LDFLAGS' variable to stuff in any flags you 1429want to pass to libtool while linking `program' (such as `-static' to 1430avoid linking uninstalled shared libtool libraries). 1431 1432 Building a libtool library is almost as trivial... note the use of 1433`libhello_la_LDFLAGS' to pass the `-version-info' (*note Versioning::) 1434option to libtool: 1435 1436 # Build a libtool library, libhello.la for installation in libdir. 1437 lib_LTLIBRARIES = libhello.la 1438 libhello_la_SOURCES = hello.c foo.c 1439 libhello_la_LDFLAGS = -version-info 3:12:1 1440 1441 The `-rpath' option is passed automatically by Automake (except for 1442libraries listed as `noinst_LTLIBRARIES'), so you should not specify it. 1443 1444 *Note Building a Shared Library: (automake)A Shared Library, for 1445more information. 1446 1447 1448File: libtool.info, Node: Configuring, Next: Distributing, Prev: Using Automake, Up: Integrating libtool 1449 14505.3 Configuring libtool 1451======================= 1452 1453Libtool requires intimate knowledge of your compiler suite and operating 1454system in order to be able to create shared libraries and link against 1455them properly. When you install the libtool distribution, a 1456system-specific libtool script is installed into your binary directory. 1457 1458 However, when you distribute libtool with your own packages (*note 1459Distributing::), you do not always know which compiler suite and 1460operating system are used to compile your package. 1461 1462 For this reason, libtool must be "configured" before it can be used. 1463This idea should be familiar to anybody who has used a GNU `configure' 1464script. `configure' runs a number of tests for system features, then 1465generates the `Makefiles' (and possibly a `config.h' header file), 1466after which you can run `make' and build the package. 1467 1468 Libtool adds its own tests to your `configure' script in order to 1469generate a libtool script for the installer's host machine. 1470 1471* Menu: 1472 1473* AC_PROG_LIBTOOL:: Configuring `libtool' in `configure.in'. 1474 1475 1476File: libtool.info, Node: AC_PROG_LIBTOOL, Up: Configuring 1477 14785.3.1 The `AC_PROG_LIBTOOL' macro 1479--------------------------------- 1480 1481If you are using GNU Autoconf (or Automake), you should add a call to 1482`AC_PROG_LIBTOOL' to your `configure.in' file. This macro adds many 1483new tests to the `configure' script so that the generated libtool 1484script will understand the characteristics of the host: 1485 1486 -- Macro: AC_PROG_LIBTOOL 1487 -- Macro: AM_PROG_LIBTOOL 1488 Add support for the `--enable-shared' and `--disable-shared' 1489 `configure' flags.(1) `AM_PROG_LIBTOOL' was the old name for this 1490 macro, and although supported at the moment is deprecated. 1491 1492 By default, this macro turns on shared libraries if they are 1493 available, and also enables static libraries if they don't 1494 conflict with the shared libraries. You can modify these defaults 1495 by calling either the `AC_DISABLE_SHARED' or `AC_DISABLE_STATIC' 1496 macros: 1497 1498 # Turn off shared libraries during beta-testing, since they 1499 # make the build process take too long. 1500 AC_DISABLE_SHARED 1501 AC_PROG_LIBTOOL 1502 1503 The user may specify modified forms of the configure flags 1504 `--enable-shared' and `--enable-static' to choose whether shared 1505 or static libraries are built based on the name of the package. 1506 For example, to have shared `bfd' and `gdb' libraries built, but 1507 not shared `libg++', you can run all three `configure' scripts as 1508 follows: 1509 1510 trick$ ./configure --enable-shared=bfd,gdb 1511 1512 In general, specifying `--enable-shared=PKGS' is the same as 1513 configuring with `--enable-shared' every package named in the 1514 comma-separated PKGS list, and every other package with 1515 `--disable-shared'. The `--enable-static=PKGS' flag behaves 1516 similarly, but it uses `--enable-static' and `--disable-static'. 1517 The same applies to the `--enable-fast-install=PKGS' flag, which 1518 uses `--enable-fast-install' and `--disable-fast-install'. 1519 1520 The package name `default' matches any packages which have not set 1521 their name in the `PACKAGE' environment variable. 1522 1523 This macro also sets the shell variable LIBTOOL_DEPS, that you can 1524 use to automatically update the libtool script if it becomes 1525 out-of-date. In order to do that, add to your `configure.in': 1526 1527 AC_PROG_LIBTOOL 1528 AC_SUBST(LIBTOOL_DEPS) 1529 1530 and, to `Makefile.in' or `Makefile.am': 1531 1532 LIBTOOL_DEPS = @LIBTOOL_DEPS@ 1533 libtool: $(LIBTOOL_DEPS) 1534 $(SHELL) ./config.status --recheck 1535 1536 If you are using GNU automake, you can omit the assignment, as 1537 automake will take care of it. You'll obviously have to create 1538 some dependency on `libtool'. 1539 1540 1541 -- Macro: AC_LIBTOOL_DLOPEN 1542 Enable checking for dlopen support. This macro should be used if 1543 the package makes use of the `-dlopen' and `-dlpreopen' flags, 1544 otherwise libtool will assume that the system does not support 1545 dlopening. The macro must be called *before* `AC_PROG_LIBTOOL'. 1546 1547 -- Macro: AC_LIBTOOL_WIN32_DLL 1548 This macro should be used if the package has been ported to build 1549 clean dlls on win32 platforms. Usually this means that any 1550 library data items are exported with `__declspec(dllexport)' and 1551 imported with `__declspec(dllimport)'. If this macro is not used, 1552 libtool will assume that the package libraries are not dll clean 1553 and will build only static libraries on win32 hosts. 1554 1555 This macro must be called *before* `AC_PROG_LIBTOOL', and 1556 provision must be made to pass `-no-undefined' to `libtool' in 1557 link mode from the package `Makefile'. Naturally, if you pass 1558 `-no-undefined', you must ensure that all the library symbols 1559 *really are* defined at link time! 1560 1561 -- Macro: AC_DISABLE_FAST_INSTALL 1562 Change the default behaviour for `AC_PROG_LIBTOOL' to disable 1563 optimization for fast installation. The user may still override 1564 this default, depending on platform support, by specifying 1565 `--enable-fast-install'. 1566 1567 -- Macro: AC_DISABLE_SHARED 1568 -- Macro: AM_DISABLE_SHARED 1569 Change the default behaviour for `AC_PROG_LIBTOOL' to disable 1570 shared libraries. The user may still override this default by 1571 specifying `--enable-shared'. 1572 1573 -- Macro: AC_DISABLE_STATIC 1574 -- Macro: AM_DISABLE_STATIC 1575 Change the default behaviour for `AC_PROG_LIBTOOL' to disable 1576 static libraries. The user may still override this default by 1577 specifying `--enable-static'. 1578 1579 The tests in `AC_PROG_LIBTOOL' also recognize the following 1580environment variables: 1581 1582 -- Variable: CC 1583 The C compiler that will be used by the generated `libtool'. If 1584 this is not set, `AC_PROG_LIBTOOL' will look for `gcc' or `cc'. 1585 1586 -- Variable: CFLAGS 1587 Compiler flags used to generate standard object files. If this is 1588 not set, `AC_PROG_LIBTOOL' will not use any such flags. It affects 1589 only the way `AC_PROG_LIBTOOL' runs tests, not the produced 1590 `libtool'. 1591 1592 -- Variable: CPPFLAGS 1593 C preprocessor flags. If this is not set, `AC_PROG_LIBTOOL' will 1594 not use any such flags. It affects only the way `AC_PROG_LIBTOOL' 1595 runs tests, not the produced `libtool'. 1596 1597 -- Variable: LD 1598 The system linker to use (if the generated `libtool' requires one). 1599 If this is not set, `AC_PROG_LIBTOOL' will try to find out what is 1600 the linker used by CC. 1601 1602 -- Variable: LDFLAGS 1603 The flags to be used by `libtool' when it links a program. If 1604 this is not set, `AC_PROG_LIBTOOL' will not use any such flags. It 1605 affects only the way `AC_PROG_LIBTOOL' runs tests, not the produced 1606 `libtool'. 1607 1608 -- Variable: LIBS 1609 The libraries to be used by `AC_PROG_LIBTOOL' when it links a 1610 program. If this is not set, `AC_PROG_LIBTOOL' will not use any 1611 such flags. It affects only the way `AC_PROG_LIBTOOL' runs tests, 1612 not the produced `libtool'. 1613 1614 -- Variable: NM 1615 Program to use rather than checking for `nm'. 1616 1617 -- Variable: RANLIB 1618 Program to use rather than checking for `ranlib'. 1619 1620 -- Variable: LN_S 1621 A command that creates a link of a program, a soft-link if 1622 possible, a hard-link otherwise. `AC_PROG_LIBTOOL' will check for 1623 a suitable program if this variable is not set. 1624 1625 -- Variable: DLLTOOL 1626 Program to use rather than checking for `dlltool'. Only meaningful 1627 for Cygwin/MS-Windows. 1628 1629 -- Variable: OBJDUMP 1630 Program to use rather than checking for `objdump'. Only meaningful 1631 for Cygwin/MS-Windows. 1632 1633 -- Variable: AS 1634 Program to use rather than checking for `as'. Only used on 1635 Cygwin/MS-Windows at the moment. 1636 1637 When you invoke the `libtoolize' program (*note Invoking 1638libtoolize::), it will tell you where to find a definition of 1639`AC_PROG_LIBTOOL'. If you use Automake, the `aclocal' program will 1640automatically add `AC_PROG_LIBTOOL' support to your `configure' script. 1641 1642 Nevertheless, it is advisable to include a copy of `libtool.m4' in 1643`acinclude.m4', so that, even if `aclocal.m4' and `configure' are 1644rebuilt for any reason, the appropriate libtool macros will be used. 1645The alternative is to hope the user will have a compatible version of 1646`libtool.m4' installed and accessible for `aclocal'. This may lead to 1647weird errors when versions don't match. 1648 1649 ---------- Footnotes ---------- 1650 1651 (1) `AC_PROG_LIBTOOL' requires that you define the `Makefile' 1652variable `top_builddir' in your `Makefile.in'. Automake does this 1653automatically, but Autoconf users should set it to the relative path to 1654the top of your build directory (`../..', for example). 1655 1656 1657File: libtool.info, Node: Distributing, Next: Static-only libraries, Prev: Configuring, Up: Integrating libtool 1658 16595.4 Including libtool in your package 1660===================================== 1661 1662In order to use libtool, you need to include the following files with 1663your package: 1664 1665`config.guess' 1666 Attempt to guess a canonical system name. 1667 1668`config.sub' 1669 Canonical system name validation subroutine script. 1670 1671`install-sh' 1672 BSD-compatible `install' replacement script. 1673 1674`ltmain.sh' 1675 A generic script implementing basic libtool functionality. 1676 1677 Note that the libtool script itself should _not_ be included with 1678your package. *Note Configuring::. 1679 1680 You should use the `libtoolize' program, rather than manually 1681copying these files into your package. Note however, that `install-sh' 1682is not copied by `libtoolize'; if you use Automake, it will take care 1683of that, otherwise you may obtain a copy from the package data directory 1684of the installed Libtool. This may change in a future Libtool version. 1685 1686* Menu: 1687 1688* Invoking libtoolize:: `libtoolize' command line options. 1689* Autoconf .o macros:: Autoconf macros that set object file names. 1690 1691 1692File: libtool.info, Node: Invoking libtoolize, Next: Autoconf .o macros, Up: Distributing 1693 16945.4.1 Invoking `libtoolize' 1695--------------------------- 1696 1697The `libtoolize' program provides a standard way to add libtool support 1698to your package. In the future, it may implement better usage 1699checking, or other features to make libtool even easier to use. 1700 1701 The `libtoolize' program has the following synopsis: 1702 1703 libtoolize [OPTION]... 1704 1705and accepts the following options: 1706 1707`--automake' 1708 Work silently, and assume that Automake libtool support is used. 1709 1710 `libtoolize --automake' is used by Automake to add libtool files to 1711 your package, when `AC_PROG_LIBTOOL' appears in your 1712 `configure.in'. 1713 1714`--copy' 1715`-c' 1716 Copy files from the libtool data directory rather than creating 1717 symlinks. 1718 1719`--debug' 1720 Dump a trace of shell script execution to standard output. This 1721 produces a lot of output, so you may wish to pipe it to `less' (or 1722 `more') or redirect to a file. 1723 1724`--dry-run' 1725`-n' 1726 Don't run any commands that modify the file system, just print them 1727 out. 1728 1729`--force' 1730`-f' 1731 Replace existing libtool files. By default, `libtoolize' won't 1732 overwrite existing files. 1733 1734`--help' 1735 Display a help message and exit. 1736 1737`--ltdl' 1738 Install libltdl in a subdirectory of your package. 1739 1740`--ltdl-tar' 1741 Add the file libltdl.tar.gz to your package. 1742 1743`--version' 1744 Print `libtoolize' version information and exit. 1745 1746 If `libtoolize' detects an explicit call to `AC_CONFIG_AUX_DIR' 1747(*note The Autoconf Manual: (autoconf)Input.) in your `configure.in', it 1748will put the files in the specified directory. 1749 1750 `libtoolize' displays hints for adding libtool support to your 1751package, as well. 1752 1753 1754File: libtool.info, Node: Autoconf .o macros, Prev: Invoking libtoolize, Up: Distributing 1755 17565.4.2 Autoconf `.o' macros 1757-------------------------- 1758 1759The Autoconf package comes with a few macros that run tests, then set a 1760variable corresponding to the name of an object file. Sometimes it is 1761necessary to use corresponding names for libtool objects. 1762 1763 Here are the names of variables that list libtool objects: 1764 1765 -- Variable: LTALLOCA 1766 Substituted by `AC_FUNC_ALLOCA' (*note Particular Function Checks: 1767 (autoconf)Particular Functions.). Is either empty, or contains 1768 `alloca.lo'. 1769 1770 -- Variable: LTLIBOBJS 1771 Substituted by `AC_REPLACE_FUNCS' (*note Generic Function Checks: 1772 (autoconf)Generic Functions.), and a few other functions. 1773 1774 Unfortunately, the stable release of Autoconf (2.13, at the time of 1775this writing) does not have any way for libtool to provide support for 1776these variables. So, if you depend on them, use the following code 1777immediately before the call to `AC_OUTPUT' in your `configure.in': 1778 1779 LTLIBOBJS=`echo "$LIBOBJS" | sed 's/\.[^.]* /.lo /g;s/\.[^.]*$/.lo/'` 1780 AC_SUBST(LTLIBOBJS) 1781 LTALLOCA=`echo "$ALLOCA" | sed 's/\.[^.]* /.lo /g;s/\.[^.]*$/.lo/'` 1782 AC_SUBST(LTALLOCA) 1783 AC_OUTPUT(...) 1784 1785 1786File: libtool.info, Node: Static-only libraries, Prev: Distributing, Up: Integrating libtool 1787 17885.5 Static-only libraries 1789========================= 1790 1791When you are developing a package, it is often worthwhile to configure 1792your package with the `--disable-shared' flag, or to override the 1793defaults for `AC_PROG_LIBTOOL' by using the `AC_DISABLE_SHARED' 1794Autoconf macro (*note The `AC_PROG_LIBTOOL' macro: AC_PROG_LIBTOOL.). 1795This prevents libtool from building shared libraries, which has several 1796advantages: 1797 1798 * compilation is twice as fast, which can speed up your development 1799 cycle, 1800 1801 * debugging is easier because you don't need to deal with any 1802 complexities added by shared libraries, and 1803 1804 * you can see how libtool behaves on static-only platforms. 1805 1806 You may want to put a small note in your package `README' to let 1807other developers know that `--disable-shared' can save them time. The 1808following example note is taken from the GIMP(1) distribution `README': 1809 1810 The GIMP uses GNU Libtool in order to build shared libraries on a 1811 variety of systems. While this is very nice for making usable 1812 binaries, it can be a pain when trying to debug a program. For that 1813 reason, compilation of shared libraries can be turned off by 1814 specifying the `--disable-shared' option to `configure'. 1815 1816 ---------- Footnotes ---------- 1817 1818 (1) GNU Image Manipulation Program, for those who haven't taken the 1819plunge. See `http://www.gimp.org/'. 1820 1821 1822File: libtool.info, Node: Versioning, Next: Library tips, Prev: Integrating libtool, Up: Top 1823 18246 Library interface versions 1825**************************** 1826 1827The most difficult issue introduced by shared libraries is that of 1828creating and resolving runtime dependencies. Dependencies on programs 1829and libraries are often described in terms of a single name, such as 1830`sed'. So, one may say "libtool depends on sed," and that is good 1831enough for most purposes. 1832 1833 However, when an interface changes regularly, we need to be more 1834specific: "Gnus 5.1 requires Emacs 19.28 or above." Here, the 1835description of an interface consists of a name, and a "version number." 1836 1837 Even that sort of description is not accurate enough for some 1838purposes. What if Emacs 20 changes enough to break Gnus 5.1? 1839 1840 The same problem exists in shared libraries: we require a formal 1841version system to describe the sorts of dependencies that programs have 1842on shared libraries, so that the dynamic linker can guarantee that 1843programs are linked only against libraries that provide the interface 1844they require. 1845 1846* Menu: 1847 1848* Interfaces:: What are library interfaces? 1849* Libtool versioning:: Libtool's versioning system. 1850* Updating version info:: Changing version information before releases. 1851* Release numbers:: Breaking binary compatibility for aesthetics. 1852 1853 1854File: libtool.info, Node: Interfaces, Next: Libtool versioning, Up: Versioning 1855 18566.1 What are library interfaces? 1857================================ 1858 1859Interfaces for libraries may be any of the following (and more): 1860 1861 * global variables: both names and types 1862 1863 * global functions: argument types and number, return types, and 1864 function names 1865 1866 * standard input, standard output, standard error, and file formats 1867 1868 * sockets, pipes, and other inter-process communication protocol 1869 formats 1870 1871 Note that static functions do not count as interfaces, because they 1872are not directly available to the user of the library. 1873 1874 1875File: libtool.info, Node: Libtool versioning, Next: Updating version info, Prev: Interfaces, Up: Versioning 1876 18776.2 Libtool's versioning system 1878=============================== 1879 1880Libtool has its own formal versioning system. It is not as flexible as 1881some, but it is definitely the simplest of the more powerful versioning 1882systems. 1883 1884 Think of a library as exporting several sets of interfaces, 1885arbitrarily represented by integers. When a program is linked against 1886a library, it may use any subset of those interfaces. 1887 1888 Libtool's description of the interfaces that a program uses is 1889simple: it encodes the least and the greatest interface numbers in the 1890resulting binary (FIRST-INTERFACE, LAST-INTERFACE). 1891 1892 The dynamic linker is guaranteed that if a library supports _every_ 1893interface number between FIRST-INTERFACE and LAST-INTERFACE, then the 1894program can be relinked against that library. 1895 1896 Note that this can cause problems because libtool's compatibility 1897requirements are actually stricter than is necessary. 1898 1899 Say `libhello' supports interfaces 5, 16, 17, 18, and 19, and that 1900libtool is used to link `test' against `libhello'. 1901 1902 Libtool encodes the numbers 5 and 19 in `test', and the dynamic 1903linker will only link `test' against libraries that support _every_ 1904interface between 5 and 19. So, the dynamic linker refuses to link 1905`test' against `libhello'! 1906 1907 In order to eliminate this problem, libtool only allows libraries to 1908declare consecutive interface numbers. So, `libhello' can declare at 1909most that it supports interfaces 16 through 19. Then, the dynamic 1910linker will link `test' against `libhello'. 1911 1912 So, libtool library versions are described by three integers: 1913 1914CURRENT 1915 The most recent interface number that this library implements. 1916 1917REVISION 1918 The implementation number of the CURRENT interface. 1919 1920AGE 1921 The difference between the newest and oldest interfaces that this 1922 library implements. In other words, the library implements all the 1923 interface numbers in the range from number `CURRENT - AGE' to 1924 `CURRENT'. 1925 1926 If two libraries have identical CURRENT and AGE numbers, then the 1927dynamic linker chooses the library with the greater REVISION number. 1928 1929 1930File: libtool.info, Node: Updating version info, Next: Release numbers, Prev: Libtool versioning, Up: Versioning 1931 19326.3 Updating library version information 1933======================================== 1934 1935If you want to use libtool's versioning system, then you must specify 1936the version information to libtool using the `-version-info' flag 1937during link mode (*note Link mode::). 1938 1939 This flag accepts an argument of the form 1940`CURRENT[:REVISION[:AGE]]'. So, passing `-version-info 3:12:1' sets 1941CURRENT to 3, REVISION to 12, and AGE to 1. 1942 1943 If either REVISION or AGE are omitted, they default to 0. Also note 1944that AGE must be less than or equal to the CURRENT interface number. 1945 1946 Here are a set of rules to help you update your library version 1947information: 1948 1949 1. Start with version information of `0:0:0' for each libtool library. 1950 1951 2. Update the version information only immediately before a public 1952 release of your software. More frequent updates are unnecessary, 1953 and only guarantee that the current interface number gets larger 1954 faster. 1955 1956 3. If the library source code has changed at all since the last 1957 update, then increment REVISION (`C:R:A' becomes `C:r+1:A'). 1958 1959 4. If any interfaces have been added, removed, or changed since the 1960 last update, increment CURRENT, and set REVISION to 0. 1961 1962 5. If any interfaces have been added since the last public release, 1963 then increment AGE. 1964 1965 6. If any interfaces have been removed since the last public release, 1966 then set AGE to 0. 1967 1968 *_Never_* try to set the interface numbers so that they correspond 1969to the release number of your package. This is an abuse that only 1970fosters misunderstanding of the purpose of library versions. Instead, 1971use the `-release' flag (*note Release numbers::), but be warned that 1972every release of your package will not be binary compatible with any 1973other release. 1974 1975 1976File: libtool.info, Node: Release numbers, Prev: Updating version info, Up: Versioning 1977 19786.4 Managing release information 1979================================ 1980 1981Often, people want to encode the name of the package release into the 1982shared library so that it is obvious to the user which package their 1983programs are linked against. This convention is used especially on 1984GNU/Linux: 1985 1986 trick$ ls /usr/lib/libbfd* 1987 /usr/lib/libbfd.a /usr/lib/libbfd.so.2.7.0.2 1988 /usr/lib/libbfd.so 1989 trick$ 1990 1991 On `trick', `/usr/lib/libbfd.so' is a symbolic link to 1992`libbfd.so.2.7.0.2', which was distributed as a part of 1993`binutils-2.7.0.2'. 1994 1995 Unfortunately, this convention conflicts directly with libtool's 1996idea of library interface versions, because the library interface 1997rarely changes at the same time that the release number does, and the 1998library suffix is never the same across all platforms. 1999 2000 So, in order to accommodate both views, you can use the `-release' 2001flag in order to set release information for libraries which you do not 2002want to use `-version-info'. For the `libbfd' example, the next 2003release which uses libtool should be built with `-release 2.9.0', which 2004will produce the following files on GNU/Linux: 2005 2006 trick$ ls /usr/lib/libbfd* 2007 /usr/lib/libbfd-2.9.0.so /usr/lib/libbfd.a 2008 /usr/lib/libbfd.so 2009 trick$ 2010 2011 In this case, `/usr/lib/libbfd.so' is a symbolic link to 2012`libbfd-2.9.0.so'. This makes it obvious that the user is dealing with 2013`binutils-2.9.0', without compromising libtool's idea of interface 2014versions. 2015 2016 Note that this option causes a modification of the library name, so 2017do not use it unless you want to break binary compatibility with any 2018past library releases. In general, you should only use `-release' for 2019package-internal libraries or for ones whose interfaces change very 2020frequently. 2021 2022 2023File: libtool.info, Node: Library tips, Next: Inter-library dependencies, Prev: Versioning, Up: Top 2024 20257 Tips for interface design 2026*************************** 2027 2028Writing a good library interface takes a lot of practice and thorough 2029understanding of the problem that the library is intended to solve. 2030 2031 If you design a good interface, it won't have to change often, you 2032won't have to keep updating documentation, and users won't have to keep 2033relearning how to use the library. 2034 2035 Here is a brief list of tips for library interface design, which may 2036help you in your exploits: 2037 2038Plan ahead 2039 Try to make every interface truly minimal, so that you won't need 2040 to delete entry points very often. 2041 2042Avoid interface changes 2043 Some people love redesigning and changing entry points just for 2044 the heck of it (note: _renaming_ a function is considered changing 2045 an entry point). Don't be one of those people. If you must 2046 redesign an interface, then try to leave compatibility functions 2047 behind so that users don't need to rewrite their existing code. 2048 2049Use opaque data types 2050 The fewer data type definitions a library user has access to, the 2051 better. If possible, design your functions to accept a generic 2052 pointer (which you can cast to an internal data type), and provide 2053 access functions rather than allowing the library user to directly 2054 manipulate the data. That way, you have the freedom to change the 2055 data structures without changing the interface. 2056 2057 This is essentially the same thing as using abstract data types and 2058 inheritance in an object-oriented system. 2059 2060Use header files 2061 If you are careful to document each of your library's global 2062 functions and variables in header files, and include them in your 2063 library source files, then the compiler will let you know if you 2064 make any interface changes by accident (*note C header files::). 2065 2066Use the `static' keyword (or equivalent) whenever possible 2067 The fewer global functions your library has, the more flexibility 2068 you'll have in changing them. Static functions and variables may 2069 change forms as often as you like... your users cannot access 2070 them, so they aren't interface changes. 2071 2072Be careful with array dimensions 2073 The number of elements in a global array is part of an interface, 2074 even if the header just declares `extern int foo[];'. This is 2075 because on i386 and some other SVR4/ELF systems, when an 2076 application references data in a shared library the size of that 2077 data (whatever its type) is included in the application 2078 executable. If you might want to change the size of an array or 2079 string then provide a pointer not the actual array. 2080 2081* Menu: 2082 2083* C header files:: How to write portable include files. 2084 2085 2086File: libtool.info, Node: C header files, Up: Library tips 2087 20887.1 Writing C header files 2089========================== 2090 2091Writing portable C header files can be difficult, since they may be read 2092by different types of compilers: 2093 2094C++ compilers 2095 C++ compilers require that functions be declared with full 2096 prototypes, since C++ is more strongly typed than C. C functions 2097 and variables also need to be declared with the `extern "C"' 2098 directive, so that the names aren't mangled. *Note C++ 2099 libraries::, for other issues relevant to using C++ with libtool. 2100 2101ANSI C compilers 2102 ANSI C compilers are not as strict as C++ compilers, but functions 2103 should be prototyped to avoid unnecessary warnings when the header 2104 file is `#include'd. 2105 2106non-ANSI C compilers 2107 Non-ANSI compilers will report errors if functions are prototyped. 2108 2109 These complications mean that your library interface headers must use 2110some C preprocessor magic in order to be usable by each of the above 2111compilers. 2112 2113 `foo.h' in the `demo' subdirectory of the libtool distribution 2114serves as an example for how to write a header file that can be safely 2115installed in a system directory. 2116 2117 Here are the relevant portions of that file: 2118 2119 /* BEGIN_C_DECLS should be used at the beginning of your declarations, 2120 so that C++ compilers don't mangle their names. Use END_C_DECLS at 2121 the end of C declarations. */ 2122 #undef BEGIN_C_DECLS 2123 #undef END_C_DECLS 2124 #ifdef __cplusplus 2125 # define BEGIN_C_DECLS extern "C" { 2126 # define END_C_DECLS } 2127 #else 2128 # define BEGIN_C_DECLS /* empty */ 2129 # define END_C_DECLS /* empty */ 2130 #endif 2131 2132 /* PARAMS is a macro used to wrap function prototypes, so that 2133 compilers that don't understand ANSI C prototypes still work, 2134 and ANSI C compilers can issue warnings about type mismatches. */ 2135 #undef PARAMS 2136 #if defined (__STDC__) || defined (_AIX) \ 2137 || (defined (__mips) && defined (_SYSTYPE_SVR4)) \ 2138 || defined(WIN32) || defined(__cplusplus) 2139 # define PARAMS(protos) protos 2140 #else 2141 # define PARAMS(protos) () 2142 #endif 2143 2144 These macros are used in `foo.h' as follows: 2145 2146 #ifndef FOO_H 2147 #define FOO_H 1 2148 2149 /* The above macro definitions. */ 2150 #include "..." 2151 2152 BEGIN_C_DECLS 2153 2154 int foo PARAMS((void)); 2155 int hello PARAMS((void)); 2156 2157 END_C_DECLS 2158 2159 #endif /* !FOO_H */ 2160 2161 Note that the `#ifndef FOO_H' prevents the body of `foo.h' from 2162being read more than once in a given compilation. 2163 2164 Also the only thing that must go outside the 2165`BEGIN_C_DECLS'/`END_C_DECLS' pair are `#include' lines. Strictly 2166speaking it is only C symbol names that need to be protected, but your 2167header files will be more maintainable if you have a single pair of of 2168these macros around the majority of the header contents. 2169 2170 You should use these definitions of `PARAMS', `BEGIN_C_DECLS', and 2171`END_C_DECLS' into your own headers. Then, you may use them to create 2172header files that are valid for C++, ANSI, and non-ANSI compilers(1). 2173 2174 Do not be naive about writing portable code. Following the tips 2175given above will help you miss the most obvious problems, but there are 2176definitely other subtle portability issues. You may need to cope with 2177some of the following issues: 2178 2179 * Pre-ANSI compilers do not always support the `void *' generic 2180 pointer type, and so need to use `char *' in its place. 2181 2182 * The `const', `inline' and `signed' keywords are not supported by 2183 some compilers, especially pre-ANSI compilers. 2184 2185 * The `long double' type is not supported by many compilers. 2186 2187 ---------- Footnotes ---------- 2188 2189 (1) We used to recommend `__P', `__BEGIN_DECLS' and `__END_DECLS'. 2190This was bad advice since symbols (even preprocessor macro names) that 2191begin with an underscore are reserved for the use of the compiler. 2192 2193 2194File: libtool.info, Node: Inter-library dependencies, Next: Dlopened modules, Prev: Library tips, Up: Top 2195 21968 Inter-library dependencies 2197**************************** 2198 2199By definition, every shared library system provides a way for 2200executables to depend on libraries, so that symbol resolution is 2201deferred until runtime. 2202 2203 An "inter-library dependency" is one in which a library depends on 2204other libraries. For example, if the libtool library `libhello' uses 2205the `cos' function, then it has an inter-library dependency on `libm', 2206the math library that implements `cos'. 2207 2208 Some shared library systems provide this feature in an 2209internally-consistent way: these systems allow chains of dependencies of 2210potentially infinite length. 2211 2212 However, most shared library systems are restricted in that they only 2213allow a single level of dependencies. In these systems, programs may 2214depend on shared libraries, but shared libraries may not depend on other 2215shared libraries. 2216 2217 In any event, libtool provides a simple mechanism for you to declare 2218inter-library dependencies: for every library `libNAME' that your own 2219library depends on, simply add a corresponding `-lNAME' option to the 2220link line when you create your library. To make an example of our 2221`libhello' that depends on `libm': 2222 2223 burger$ libtool --mode=link gcc -g -O -o libhello.la foo.lo hello.lo \ 2224 -rpath /usr/local/lib -lm 2225 burger$ 2226 2227 When you link a program against `libhello', you don't need to 2228specify the same `-l' options again: libtool will do that for you, in 2229order to guarantee that all the required libraries are found. This 2230restriction is only necessary to preserve compatibility with static 2231library systems and simple dynamic library systems. 2232 2233 Some platforms, such as AIX, do not even allow you this flexibility. 2234In order to build a shared library, it must be entirely self-contained 2235(that is, have references only to symbols that are found in the `.lo' 2236files or the specified `-l' libraries), and you need to specify the 2237-NO-UNDEFINED flag. By default, libtool builds only static libraries 2238on these kinds of platforms. 2239 2240 The simple-minded inter-library dependency tracking code of libtool 2241releases prior to 1.2 was disabled because it was not clear when it was 2242possible to link one library with another, and complex failures would 2243occur. A more complex implementation of this concept was re-introduced 2244before release 1.3, but it has not been ported to all platforms that 2245libtool supports. The default, conservative behavior is to avoid 2246linking one library with another, introducing their inter-dependencies 2247only when a program is linked with them. 2248 2249 2250File: libtool.info, Node: Dlopened modules, Next: Using libltdl, Prev: Inter-library dependencies, Up: Top 2251 22529 Dlopened modules 2253****************** 2254 2255It can sometimes be confusing to discuss "dynamic linking", because the 2256term is used to refer to two different concepts: 2257 2258 1. Compiling and linking a program against a shared library, which is 2259 resolved automatically at run time by the dynamic linker. In this 2260 process, dynamic linking is transparent to the application. 2261 2262 2. The application calling functions such as `dlopen',(1) which load 2263 arbitrary, user-specified modules at runtime. This type of dynamic 2264 linking is explicitly controlled by the application. 2265 2266 To mitigate confusion, this manual refers to the second type of 2267dynamic linking as "dlopening" a module. 2268 2269 The main benefit to dlopening object modules is the ability to access 2270compiled object code to extend your program, rather than using an 2271interpreted language. In fact, dlopen calls are frequently used in 2272language interpreters to provide an efficient way to extend the 2273language. 2274 2275 As of version 1.5.20, libtool provides support for dlopened modules. 2276However, you should indicate that your package is willing to use such 2277support, by using the macro `AC_LIBTOOL_DLOPEN' in `configure.in'. If 2278this macro is not used (or it is used _after_ `AC_PROG_LIBTOOL'), 2279libtool will assume no dlopening mechanism is available, and will try 2280to simulate it. 2281 2282 This chapter discusses how you as a dlopen application developer 2283might use libtool to generate dlopen-accessible modules. 2284 2285* Menu: 2286 2287* Building modules:: Creating dlopenable objects and libraries. 2288* Dlpreopening:: Dlopening that works on static platforms. 2289* Finding the dlname:: Choosing the right file to `dlopen'. 2290* Dlopen issues:: Unresolved problems that need your attention. 2291 2292 ---------- Footnotes ---------- 2293 2294 (1) HP-UX, to be different, uses a function named `shl_load'. 2295 2296 2297File: libtool.info, Node: Building modules, Next: Dlpreopening, Up: Dlopened modules 2298 22999.1 Building modules to dlopen 2300============================== 2301 2302On some operating systems, a program symbol must be specially declared 2303in order to be dynamically resolved with the `dlsym' (or equivalent) 2304function. 2305 2306 Libtool provides the `-export-dynamic' and `-module' link flags 2307(*note Link mode::), which do this declaration. You need to use these 2308flags if you are linking an application program that dlopens other 2309modules or a libtool library that will also be dlopened. 2310 2311 For example, if we wanted to build a shared library, `libhello', 2312that would later be dlopened by an application, we would add `-module' 2313to the other link flags: 2314 2315 burger$ libtool --mode=link gcc -module -o libhello.la foo.lo \ 2316 hello.lo -rpath /usr/local/lib -lm 2317 burger$ 2318 2319 If symbols from your _executable_ are needed to satisfy unresolved 2320references in a library you want to dlopen you will have to use the flag 2321`-export-dynamic'. You should use `-export-dynamic' while linking the 2322executable that calls dlopen: 2323 2324 burger$ libtool --mode=link gcc -export-dynamic -o hell-dlopener main.o 2325 burger$ 2326 2327 2328File: libtool.info, Node: Dlpreopening, Next: Finding the dlname, Prev: Building modules, Up: Dlopened modules 2329 23309.2 Dlpreopening 2331================ 2332 2333Libtool provides special support for dlopening libtool object and 2334libtool library files, so that their symbols can be resolved _even on 2335platforms without any `dlopen' and `dlsym' functions_. 2336 2337 Consider the following alternative ways of loading code into your 2338program, in order of increasing "laziness": 2339 2340 1. Linking against object files that become part of the program 2341 executable, whether or not they are referenced. If an object file 2342 cannot be found, then the linker refuses to create the executable. 2343 2344 2. Declaring a static library to the linker, so that it is searched 2345 at link time in order to satisfy any undefined references in the 2346 above object files. If the static library cannot be found, then 2347 the linker refuses to link the executable. 2348 2349 3. Declaring a shared library to the runtime linker, so that it is 2350 searched at runtime in order to satisfy any undefined references 2351 in the above files. If the shared library cannot be found, then 2352 the dynamic linker aborts the program before it runs. 2353 2354 4. Dlopening a module, so that the application can resolve its own, 2355 dynamically-computed references. If there is an error opening the 2356 module, or the module is not found, then the application can 2357 recover without crashing. 2358 2359 Libtool emulates `-dlopen' on static platforms by linking objects 2360into the program at compile time, and creating data structures that 2361represent the program's symbol table. 2362 2363 In order to use this feature, you must declare the objects you want 2364your application to dlopen by using the `-dlopen' or `-dlpreopen' flags 2365when you link your program (*note Link mode::). 2366 2367 -- Structure: struct lt_dlsymlist { const char *NAME; lt_ptr ADDRESS; } 2368 The NAME attribute is a null-terminated character string of the 2369 symbol name, such as `"fprintf"'. The ADDRESS attribute is a 2370 generic pointer to the appropriate object, such as `&fprintf'. 2371 2372 -- Variable: const lt_dlsymlist * lt_preloaded_symbols 2373 An array of LT_SYMBOL structures, representing all the preloaded 2374 symbols linked into the program. For each `-dlpreloaded' file 2375 there is an element with the NAME of the file and a ADDRESS of 2376 `0', followed by all symbols exported from this file. For the 2377 executable itself the special name @PROGRAM@ is used. The last 2378 element has a NAME and ADDRESS of `0'. 2379 2380 Some compilers may allow identifiers which are not valid in ANSI C, 2381such as dollar signs. Libtool only recognizes valid ANSI C symbols (an 2382initial ASCII letter or underscore, followed by zero or more ASCII 2383letters, digits, and underscores), so non-ANSI symbols will not appear 2384in LT_PRELOADED_SYMBOLS. 2385 2386 2387File: libtool.info, Node: Finding the dlname, Next: Dlopen issues, Prev: Dlpreopening, Up: Dlopened modules 2388 23899.3 Finding the correct name to dlopen 2390====================================== 2391 2392After a library has been linked with `-module', it can be dlopened. 2393Unfortunately, because of the variation in library names, your package 2394needs to determine the correct file to dlopen. 2395 2396 The most straightforward and flexible implementation is to determine 2397the name at runtime, by finding the installed `.la' file, and searching 2398it for the following lines: 2399 2400 # The name that we can `dlopen'. 2401 dlname='DLNAME' 2402 2403 If DLNAME is empty, then the library cannot be dlopened. Otherwise, 2404it gives the dlname of the library. So, if the library was installed 2405as `/usr/local/lib/libhello.la', and the DLNAME was `libhello.so.3', 2406then `/usr/local/lib/libhello.so.3' should be dlopened. 2407 2408 If your program uses this approach, then it should search the 2409directories listed in the `LD_LIBRARY_PATH'(1) environment variable, as 2410well as the directory where libraries will eventually be installed. 2411Searching this variable (or equivalent) will guarantee that your 2412program can find its dlopened modules, even before installation, 2413provided you have linked them using libtool. 2414 2415 ---------- Footnotes ---------- 2416 2417 (1) `LIBPATH' on AIX, and `SHLIB_PATH' on HP-UX. 2418 2419 2420File: libtool.info, Node: Dlopen issues, Prev: Finding the dlname, Up: Dlopened modules 2421 24229.4 Unresolved dlopen issues 2423============================ 2424 2425The following problems are not solved by using libtool's dlopen support: 2426 2427 * Dlopen functions are generally only available on shared library 2428 platforms. If you want your package to be portable to static 2429 platforms, you have to use either libltdl (*note Using libltdl::) 2430 or develop your own alternatives to dlopening dynamic code. Most 2431 reasonable solutions involve writing wrapper functions for the 2432 `dlopen' family, which do package-specific tricks when dlopening 2433 is unsupported or not available on a given platform. 2434 2435 * There are major differences in implementations of the `dlopen' 2436 family of functions. Some platforms do not even use the same 2437 function names (notably HP-UX, with its `shl_load' family). 2438 2439 * The application developer must write a custom search function in 2440 order to discover the correct module filename to supply to 2441 `dlopen'. 2442 2443 2444File: libtool.info, Node: Using libltdl, Next: Other languages, Prev: Dlopened modules, Up: Top 2445 244610 Using libltdl 2447**************** 2448 2449Libtool provides a small library, called `libltdl', that aims at hiding 2450the various difficulties of dlopening libraries from programmers. It 2451consists of a header-file and a small C source file that can be 2452distributed with applications that need dlopening functionality. On 2453some platforms, whose dynamic linkers are too limited for a simple 2454implementation of `libltdl' services, it requires GNU DLD, or it will 2455only emulate dynamic linking with libtool's dlpreopening mechanism. 2456 2457libltdl supports currently the following dynamic linking mechanisms: 2458 2459 * `dlopen' (Solaris, Linux and various BSD flavors) 2460 2461 * `shl_load' (HP-UX) 2462 2463 * `LoadLibrary' (Win16 and Win32) 2464 2465 * `load_add_on' (BeOS) 2466 2467 * GNU DLD (emulates dynamic linking for static libraries) 2468 2469 * libtool's dlpreopen (see *note Dlpreopening::) 2470 2471libltdl is licensed under the terms of the GNU Library General Public 2472License, with the following exception: 2473 2474 As a special exception to the GNU Lesser General Public License, 2475 if you distribute this file as part of a program or library that 2476 is built using GNU libtool, you may include it under the same 2477 distribution terms that you use for the rest of that program. 2478 2479* Menu: 2480 2481* Libltdl interface:: How to use libltdl in your programs. 2482* Modules for libltdl:: Creating modules that can be `dlopen'ed. 2483* Thread Safety in libltdl:: Registering callbacks for multi-thread safety. 2484* User defined module data:: Associating data with loaded modules. 2485* Module loaders for libltdl:: Creating user defined module loaders. 2486* Distributing libltdl:: How to distribute libltdl with your package. 2487 2488 2489File: libtool.info, Node: Libltdl interface, Next: Modules for libltdl, Up: Using libltdl 2490 249110.1 How to use libltdl in your programs 2492======================================== 2493 2494The libltdl API is similar to the dlopen interface of Solaris and Linux, 2495which is very simple but powerful. 2496 2497To use libltdl in your program you have to include the header file 2498`ltdl.h': 2499 2500 #include <ltdl.h> 2501 2502The last release of libltdl used some symbols that violated the POSIX 2503namespace conventions. These symbols are now deprecated, and have been 2504replaced by those described here. If you have code that relies on the 2505old deprecated symbol names, defining `LT_NON_POSIX_NAMESPACE' before 2506you include `ltdl.h' provides conversion macros. Whichever set of 2507symbols you use, the new api is not binary compatible with the last, so 2508you will need to recompile your application in order to use this 2509version of libltdl. 2510 2511Note that libltdl is not threadsafe, i.e. a multithreaded application 2512has to use a mutex for libltdl. It was reported that GNU/Linux's glibc 25132.0's `dlopen' with `RTLD_LAZY' (which libltdl uses by default) is not 2514thread-safe, but this problem is supposed to be fixed in glibc 2.1. On 2515the other hand, `RTLD_NOW' was reported to introduce problems in 2516multi-threaded applications on FreeBSD. Working around these problems 2517is left as an exercise for the reader; contributions are certainly 2518welcome. 2519 2520The following types are defined in `ltdl.h': 2521 2522 -- Type: lt_ptr 2523 `lt_ptr' is a generic pointer. 2524 2525 -- Type: lt_dlhandle 2526 `lt_dlhandle' is a module "handle". Every lt_dlopened module has 2527 a handle associated with it. 2528 2529 -- Type: lt_dlsymlist 2530 `lt_dlsymlist' is a symbol list for dlpreopened modules. This 2531 structure is described in *note Dlpreopening::. 2532 2533libltdl provides the following functions: 2534 2535 -- Function: int lt_dlinit (void) 2536 Initialize libltdl. This function must be called before using 2537 libltdl and may be called several times. Return 0 on success, 2538 otherwise the number of errors. 2539 2540 -- Function: int lt_dlexit (void) 2541 Shut down libltdl and close all modules. This function will only 2542 then shut down libltdl when it was called as many times as 2543 `lt_dlinit' has been successfully called. Return 0 on success, 2544 otherwise the number of errors. 2545 2546 -- Function: lt_dlhandle lt_dlopen (const char *FILENAME) 2547 Open the module with the file name FILENAME and return a handle 2548 for it. `lt_dlopen' is able to open libtool dynamic modules, 2549 preloaded static modules, the program itself and native dynamic 2550 libraries. 2551 2552 Unresolved symbols in the module are resolved using its dependency 2553 libraries (not implemented yet) and previously dlopened modules. 2554 If the executable using this module was linked with the 2555 `-export-dynamic' flag, then the global symbols in the executable 2556 will also be used to resolve references in the module. 2557 2558 If FILENAME is `NULL' and the program was linked with 2559 `-export-dynamic' or `-dlopen self', `lt_dlopen' will return a 2560 handle for the program itself, which can be used to access its 2561 symbols. 2562 2563 If libltdl cannot find the library and the file name FILENAME does 2564 not have a directory component it will additionally search in the 2565 following search paths for the module (in the order as follows): 2566 2567 1. user-defined search path: This search path can be changed by 2568 the program using the functions `lt_dlsetsearchpath', 2569 `lt_dladdsearchdir' and `lt_dlinsertsearchdir'. 2570 2571 2. libltdl's search path: This search path is the value of the 2572 environment variable LTDL_LIBRARY_PATH. 2573 2574 3. system library search path: The system dependent library 2575 search path (e.g. on Linux it is LD_LIBRARY_PATH). 2576 2577 Each search path must be a colon-separated list of absolute 2578 directories, for example, `"/usr/lib/mypkg:/lib/foo"'. 2579 2580 If the same module is loaded several times, the same handle is 2581 returned. If `lt_dlopen' fails for any reason, it returns `NULL'. 2582 2583 -- Function: lt_dlhandle lt_dlopenext (const char *FILENAME) 2584 The same as `lt_dlopen', except that it tries to append different 2585 file name extensions to the file name. If the file with the file 2586 name FILENAME cannot be found libltdl tries to append the 2587 following extensions: 2588 2589 1. the libtool archive extension `.la' 2590 2591 2. the extension used for native dynamic libraries on the host 2592 platform, e.g., `.so', `.sl', etc. 2593 2594 This lookup strategy was designed to allow programs that don't 2595 have knowledge about native dynamic libraries naming conventions 2596 to be able to `dlopen' such libraries as well as libtool modules 2597 transparently. 2598 2599 -- Function: int lt_dlclose (lt_dlhandle HANDLE) 2600 Decrement the reference count on the module HANDLE. If it drops 2601 to zero and no other module depends on this module, then the 2602 module is unloaded. Return 0 on success. 2603 2604 -- Function: lt_ptr lt_dlsym (lt_dlhandle HANDLE, const char *NAME) 2605 Return the address in the module HANDLE, where the symbol given by 2606 the null-terminated string NAME is loaded. If the symbol cannot 2607 be found, `NULL' is returned. 2608 2609 -- Function: const char * lt_dlerror (void) 2610 Return a human readable string describing the most recent error 2611 that occurred from any of libltdl's functions. Return `NULL' if 2612 no errors have occurred since initialization or since it was last 2613 called. 2614 2615 -- Function: int lt_dlpreload (const lt_dlsymlist *PRELOADED) 2616 Register the list of preloaded modules PRELOADED. If PRELOADED is 2617 `NULL', then all previously registered symbol lists, except the 2618 list set by `lt_dlpreload_default', are deleted. Return 0 on 2619 success. 2620 2621 -- Function: int lt_dlpreload_default (const lt_dlsymlist *PRELOADED) 2622 Set the default list of preloaded modules to PRELOADED, which 2623 won't be deleted by `lt_dlpreload'. Note that this function does 2624 _not_ require libltdl to be initialized using `lt_dlinit' and can 2625 be used in the program to register the default preloaded modules. 2626 Instead of calling this function directly, most programs will use 2627 the macro `LTDL_SET_PRELOADED_SYMBOLS'. 2628 2629 Return 0 on success. 2630 2631 -- Macro: LTDL_SET_PRELOADED_SYMBOLS 2632 Set the default list of preloaded symbols. Should be used in your 2633 program to initialize libltdl's list of preloaded modules. 2634 2635 #include <ltdl.h> 2636 2637 int main() { 2638 /* ... */ 2639 LTDL_SET_PRELOADED_SYMBOLS(); 2640 /* ... */ 2641 } 2642 2643 -- Function: int lt_dladdsearchdir (const char *SEARCH_DIR) 2644 Append the search directory SEARCH_DIR to the current user-defined 2645 library search path. Return 0 on success. 2646 2647 -- Function: int lt_dlinsertsearchdir (const char *BEFORE, 2648 const char *SEARCH_DIR) 2649 Insert the search directory SEARCH_DIR into the user-defined 2650 library search path, immediately before the element starting at 2651 address BEFORE. If BEFORE is `NULL', then SEARCH_DIR is appending 2652 as if `lt_dladdsearchdir' had been called. Return 0 on success. 2653 2654 -- Function: int lt_dlsetsearchpath (const char *SEARCH_PATH) 2655 Replace the current user-defined library search path with 2656 SEARCH_PATH, which must be a colon-separated list of absolute 2657 directories. Return 0 on success. 2658 2659 -- Function: const char * lt_dlgetsearchpath (void) 2660 Return the current user-defined library search path. 2661 2662 -- Function: int lt_dlforeachfile (const char *SEARCH_PATH, 2663 int (*FUNC) (const char *FILENAME, lt_ptr DATA), lt_ptr DATA) 2664 In some applications you may not want to load individual modules 2665 with known names, but rather find all of the modules in a set of 2666 directories and load them all during initialisation. With this 2667 function you can have libltdl scan the colon delimited directory 2668 list in SEARCH_PATH for candidates, and pass them, along with DATA 2669 to your own callback function, FUNC. If SEACH_PATH is `NULL', 2670 then search all of the standard locations that `lt_dlopen' would 2671 examine. This function will continue to make calls to FUNC for 2672 each file that it discovers in SEARCH_PATH until one of these 2673 calls returns non-zero, or until the files are exhausted. 2674 `lt_dlforeachfile' returns value returned by the last call made to 2675 FUNC. 2676 2677 For example you could define FUNC to build an ordered "argv"-like 2678 vector of files using DATA to hold the address of the start of the 2679 vector. 2680 2681 -- Function: int lt_dlmakeresident (lt_dlhandle HANDLE) 2682 Mark a module so that it cannot be `lt_dlclose'd. This can be 2683 useful if a module implements some core functionality in your 2684 project, which would cause your code to crash if removed. Return 2685 0 on success. 2686 2687 If you use `lt_dlopen (NULL)' to get a HANDLE for the running 2688 binary, that handle will always be marked as resident, and 2689 consequently cannot be successfully `lt_dlclose'd. 2690 2691 -- Function: int lt_dlisresident (lt_dlhandle HANDLE) 2692 Check whether a particular module has been marked as resident, 2693 returning 1 if it has or 0 otherwise. If there is an error while 2694 executing this function, return -1 and set an error message for 2695 retrieval with `lt_dlerror'. 2696 2697 -- Variable: lt_ptr (*) (size_t SIZE) lt_dlmalloc 2698 -- Variable: lt_ptr (*) (lt_ptr PTR, size_t SIZE) lt_dlrealloc 2699 -- Variable: void (*) (lt_ptr PTR) lt_dlfree 2700 These variables are set to `malloc', `realloc' and `free' by 2701 default, but you can set them to any other functions that provide 2702 equivalent functionality. If you change any of these function 2703 pointers, you will almost certainly need to change all three to 2704 point into the same malloc library. Strange things will happen if 2705 you allocate memory from one library, and then pass it to an 2706 implementation of `free' that doesn't know what book keeping the 2707 allocator used. 2708 2709 You must not modify any of their values after calling any libltdl 2710 function other than `lt_dlpreopen_default' or the macro 2711 `LTDL_SET_PRELOADED_SYMBOLS'. 2712 2713 2714File: libtool.info, Node: Modules for libltdl, Next: Thread Safety in libltdl, Prev: Libltdl interface, Up: Using libltdl 2715 271610.2 Creating modules that can be `dlopen'ed 2717============================================ 2718 2719Libtool modules are like normal libtool libraries with a few exceptions: 2720 2721 You have to link the module with libtool's `-module' switch, and you 2722should link any program that is intended to dlopen the module with 2723`-dlopen modulename.la' so that libtool can dlpreopen the module on 2724platforms which don't support dlopening. If the module depends on any 2725other libraries, make sure you specify them either when you link the 2726module or when you link programs that dlopen it. If you want to 2727disable *note Versioning:: for a specific module you should link it 2728with the `-avoid-version' switch. Note that libtool modules don't need 2729to have a "lib" prefix. However, automake 1.4 or higher is required to 2730build such modules. 2731 2732 Usually a set of modules provide the same interface, i.e, exports 2733the same symbols, so that a program can dlopen them without having to 2734know more about their internals. In order to avoid symbol conflicts 2735all exported symbols must be prefixed with "modulename_LTX_" 2736(`modulename' is the name of the module). Internal symbols must be 2737named in such a way that they won't conflict with other modules, for 2738example, by prefixing them with "_modulename_". Although some 2739platforms support having the same symbols defined more than once it is 2740generally not portable and it makes it impossible to dlpreopen such 2741modules. libltdl will automatically cut the prefix off to get the real 2742name of the symbol. Additionally, it supports modules which don't use 2743a prefix so that you can also dlopen non-libtool modules. 2744 2745 `foo1.c' gives an example of a portable libtool module. Exported 2746symbols are prefixed with "foo1_LTX_", internal symbols with "_foo1_". 2747Aliases are defined at the beginning so that the code is more readable. 2748 2749 /* aliases for the exported symbols */ 2750 #define foo foo1_LTX_foo 2751 #define bar foo1_LTX_bar 2752 2753 /* a global variable definition */ 2754 int bar = 1; 2755 2756 /* a private function */ 2757 int _foo1_helper() { 2758 return bar; 2759 } 2760 2761 /* an exported function */ 2762 int foo() { 2763 return _foo1_helper(); 2764 } 2765 2766The `Makefile.am' contains the necessary rules to build the module 2767`foo1.la': 2768 2769 ... 2770 lib_LTLIBRARIES = foo1.la 2771 2772 foo1_la_SOURCES = foo1.c 2773 foo1_la_LDFLAGS = -module 2774 ... 2775 2776 2777File: libtool.info, Node: Thread Safety in libltdl, Next: User defined module data, Prev: Modules for libltdl, Up: Using libltdl 2778 277910.3 Using libtldl in a multi threaded environment 2780================================================== 2781 2782Using the `lt_dlmutex_register()' function, and by providing some 2783appropriate callback function definitions, libltdl can be used in a 2784multi-threaded environment. 2785 2786 -- Type: void lt_dlmutex_lock (void) 2787 This is the type of a function pointer holding the address of a 2788 function which will be called at the start of parts of the libltdl 2789 implementation code which require a mutex lock. 2790 2791 Because libltdl is inherantly recursive, it is important that the 2792 locking mechanism employed by these callback functions are 2793 reentrant, or else strange problems will occur. 2794 2795 -- Type: void lt_dlmutex_unlock (void) 2796 The type of a matching unlock function. 2797 2798 -- Type: void lt_dlmutex_seterror (const char *ERROR); 2799 Many of the functions in the libltdl API have a special return 2800 value to indicate to the client that an error has occurred. 2801 Normally (in single threaded applications) a string describing 2802 that error can be retrieved from internal storage with 2803 `lt_dlerror()'. 2804 2805 A function of this type must be registered with the library in 2806 order for it to work in a multi-threaded context. The function 2807 should store any error message passed in thread local storage. 2808 2809 -- Type: const char * lt_dlmutex_geterror (void) 2810 The type of a matching callback function to retrieve the last 2811 stored error message from thread local storage. 2812 2813 When regeistered correctly this function will be used by 2814 `lt_dlerror())' from all threads to retrieve error messages for the 2815 client. 2816 2817 -- Function: int lt_dlmutex_register (lt_dlmutex_lock *LOCK, 2818 lt_dlmutex_unlock *UNLOCK, lt_dlmutex_set_error *SETERROR, 2819 lt_dlmutex_geterror *GETERROR) 2820 Use this function to register one of each of function ttypes 2821 described above in preparation for multi-threaded use of libltdl. 2822 All arguments must be valid non-`NULL' function addresses, or else 2823 all `NULL' to return to single threaded operation. 2824 2825 2826File: libtool.info, Node: User defined module data, Next: Module loaders for libltdl, Prev: Thread Safety in libltdl, Up: Using libltdl 2827 282810.4 Data associated with loaded modules 2829======================================== 2830 2831Some of the internal information about each loaded module that is 2832maintained by libltdl is available to the user, in the form of this 2833structure: 2834 2835 -- Type: struct lt_dlinfo { char *FILENAME; char *NAME; int REF_COUNT; 2836 } 2837 `lt_dlinfo' is used to store information about a module. The 2838 FILENAME attribute is a null-terminated character string of the 2839 real module file name. If the module is a libtool module then 2840 NAME is its module name (e.g. `"libfoo"' for `"dir/libfoo.la"'), 2841 otherwise it is set to `NULL'. The REF_COUNT attribute is a 2842 reference counter that describes how often the same module is 2843 currently loaded. 2844 2845 The following function will return a pointer to libltdl's internal 2846copy of this structure for the given HANDLE: 2847 2848 -- Function: const lt_dlinfo * lt_dlgetinfo (lt_dlhandle HANDLE) 2849 Return a pointer to a struct that contains some information about 2850 the module HANDLE. The contents of the struct must not be 2851 modified. Return `NULL' on failure. 2852 2853 Furthermore, in order to save you from having to keep a list of the 2854handles of all the modules you have loaded, these functions allow you to 2855iterate over libltdl's list of loaded modules: 2856 2857 -- Function: int lt_dlforeach 2858 (int (*FUNC) (lt_dlhandle HANDLE, lt_ptr DATA), lt_ptr DATA) 2859 For each loaded module call the function FUNC. The argument 2860 HANDLE is the handle of one of the loaded modules, DATA is the 2861 DATA argument passed to `lt_dlforeach'. As soon as FUNC returns a 2862 non-zero value for one of the handles, `lt_dlforeach' will stop 2863 calling FUNC and immediately return 1. Otherwise 0 is returned. 2864 2865 -- Function: lt_dlhandle lt_dlhandle_next (lt_dlhandle place) 2866 Iterate over the loaded module handles, returning the first handle 2867 in the list if PLACE is `NULL', and the next one on subsequent 2868 calls. If PLACE is the last element in the list of loaded 2869 modules, this function returns `NULL'. 2870 2871 Of course, you would still need to maintain your own list of loaded 2872module handles to parallel the list maintained by libltdl if there are 2873any other data that you need to associate with each handle for the 2874purposes of your application. However, if you use the following API 2875calls to associate your application data with individual module handles 2876as they are loaded there is actually no need to do that. You must 2877first obtain a unique caller id from libltdl which you subsequently use 2878to retrieve the data you stored earlier. This allows for different 2879libraries that each wish to store their own data against loaded modules 2880to do so without interfering with one another's data. 2881 2882 -- Type: lt_dlcaller_id 2883 The opaque type used to hold individual data set keys. 2884 2885 -- Function: lt_dlcaller_id lt_dlcaller_register (void) 2886 Use this to obtain a unique key to store and retrieve individual 2887 sets of per module data. 2888 2889 -- Function: lt_ptr lt_dlcaller_set_data (lt_dlcaller_id KEY, 2890 lt_dlhandle HANDLE, lt_ptr DATA) 2891 Set DATA as the set of data uniquely associated with KEY and 2892 HANDLE for later retrieval. This function returns the DATA 2893 previously associated with KEY and HANDLE if any. A result of 0, 2894 may indicate that a diagnostic for the last error (if any) is 2895 available from `lt_dlerror()'. 2896 2897 For example, to correctly remove some associated data: 2898 2899 lt_ptr stale = lt_dlcaller_set_data (key, handle, 0); 2900 if (stale == NULL) 2901 { 2902 char *error_msg = lt_dlerror (); 2903 2904 if (error_msg != NULL) 2905 { 2906 my_error_handler (error_msg); 2907 return STATUS_FAILED; 2908 } 2909 } 2910 else 2911 { 2912 free (stale); 2913 } 2914 2915 -- Function: lt_ptr lt_dlcaller_get_data (lt_dlcaller_id KEY, 2916 lt_dlhandle HANDLE) 2917 Return the address of the data associated with KEY and HANDLE, or 2918 else `NULL' if there is none. 2919 2920 The preceding functions can be combined with `lt_dlforeach' to 2921implement search and apply operations without the need for your 2922application to track the modules that have been loaded and unloaded: 2923 2924 int 2925 my_dlcaller_callback (lt_dlhandle handle, lt_ptr key_ptr) 2926 { 2927 struct my_module_data *my_data; 2928 2929 my_data = lt_dlcaller_get_data (handle, (lt_dlcaller_id) *key_ptr); 2930 2931 return process (my_data); 2932 } 2933 2934 int 2935 my_dlcaller_foreach (lt_dlcaller_id key) 2936 { 2937 lt_dlforeach (my_dlcaller_callback, (lt_ptr) &key); 2938 } 2939 2940 2941File: libtool.info, Node: Module loaders for libltdl, Next: Distributing libltdl, Prev: User defined module data, Up: Using libltdl 2942 294310.5 How to create and register new module loaders 2944================================================== 2945 2946Sometimes libltdl's many ways of gaining access to modules are not 2947sufficient for the purposes of a project. You can write your own 2948loader, and register it with libltdl so that `lt_dlopen' will be able 2949to use it. 2950 2951 Writing a loader involves writing at least three functions which can 2952be called by `lt_dlopen', `lt_dlsym' and `lt_dlclose'. Optionally, 2953you can provide a finalisation function to perform any cleanup 2954operations when `lt_dlexit' executes, and a symbol prefix string which 2955will be prepended to any symbols passed to `lt_dlsym'. These functions 2956must match the function pointer types below, after which they can be 2957allocated to an instance of `lt_user_dlloader' and registered. 2958 2959 Registering the loader requires that you choose a name for it, so 2960that it can be recognised by `lt_dlloader_find' and removed with 2961`lt_dlloader_remove'. The name you choose must be unique, and not 2962already in use by libltdl's builtin loaders: 2963 2964"dlopen" 2965 The system dynamic library loader, if one exists. 2966 2967"dld" 2968 The GNU dld loader, if `libdld' was installed when libltdl was 2969 built. 2970 2971"dlpreload" 2972 The loader for `lt_dlopen'ing of preloaded static modules. 2973 2974 The prefix "dl" is reserved for loaders supplied with future 2975versions of libltdl, so you should not use that for your own loader 2976names. 2977 2978The following types are defined in `ltdl.h': 2979 2980 -- Type: lt_module 2981 `lt_module' is a dlloader dependent module. The dynamic module 2982 loader extensions communicate using these low level types. 2983 2984 -- Type: lt_dlloader 2985 `lt_dlloader' is a handle for module loader types. 2986 2987 -- Type: lt_user_data 2988 `lt_user_data' is used for specifying loader instance data. 2989 2990 -- Type: struct lt_user_dlloader {const char *SYM_PREFIX; 2991 lt_module_open *MODULE_OPEN; lt_module_close *MODULE_CLOSE; 2992 lt_find_sym *FIND_SYM; lt_dlloader_exit *DLLOADER_EXIT; } 2993 If you want to define a new way to open dynamic modules, and have 2994 the `lt_dlopen' API use it, you need to instantiate one of these 2995 structures and pass it to `lt_dlloader_add'. You can pass whatever 2996 you like in the DLLOADER_DATA field, and it will be passed back as 2997 the value of the first parameter to each of the functions 2998 specified in the function pointer fields. 2999 3000 -- Type: lt_module lt_module_open (const char *FILENAME) 3001 The type of the loader function for an `lt_dlloader' module 3002 loader. The value set in the dlloader_data field of the `struct 3003 lt_user_dlloader' structure will be passed into this function in 3004 the LOADER_DATA parameter. Implementation of such a function 3005 should attempt to load the named module, and return an `lt_module' 3006 suitable for passing in to the associated `lt_module_close' and 3007 `lt_sym_find' function pointers. If the function fails it should 3008 return `NULL', and set the error message with `lt_dlseterror'. 3009 3010 -- Type: int lt_module_close (lt_user_data LOADER_DATA, 3011 lt_module MODULE) 3012 The type of the unloader function for a user defined module loader. 3013 Implementatation of such a function should attempt to release any 3014 resources tied up by the MODULE module, and then unload it from 3015 memory. If the function fails for some reason, set the error 3016 message with `lt_dlseterror' and return non-zero. 3017 3018 -- Type: lt_ptr lt_find_sym (lt_module MODULE, const char *SYMBOL) 3019 The type of the symbol lookup function for a user defined module 3020 loader. Implementation of such a function should return the 3021 address of the named SYMBOL in the module MODULE, or else set the 3022 error message with `lt_dlseterror' and return `NULL' if lookup 3023 fails. 3024 3025 -- Type: int lt_dlloader_exit (lt_user_data LOADER_DATA) 3026 The type of the finalisation function for a user defined module 3027 loader. Implementation of such a function should free any 3028 resources associated with the loader, including any user specified 3029 data in the `dlloader_data' field of the `lt_user_dlloader'. If 3030 non-`NULL', the function will be called by `lt_dlexit', and 3031 `lt_dlloader_remove'. 3032 3033 For example: 3034 3035 int 3036 register_myloader (void) 3037 { 3038 lt_user_dlloader dlloader; 3039 3040 /* User modules are responsible for their own initialisation. */ 3041 if (myloader_init () != 0) 3042 return MYLOADER_INIT_ERROR; 3043 3044 dlloader.sym_prefix = NULL; 3045 dlloader.module_open = myloader_open; 3046 dlloader.module_close = myloader_close; 3047 dlloader.find_sym = myloader_find_sym. 3048 dlloader.dlloader_exit = myloader_exit; 3049 dlloader.dlloader_data = (lt_user_data)myloader_function; 3050 3051 /* Add my loader as the default module loader. */ 3052 if (lt_dlloader_add (lt_dlloader_next (NULL), &dlloader, "myloader") \ 3053 != 0) 3054 return ERROR; 3055 3056 return OK; 3057 } 3058 3059 Note that if there is any initialisation required for the loader, it 3060must be performed manually before the loader is registered - libltdl 3061doesn't handle user loader initialisation. 3062 3063 Finalisation _is_ handled by libltdl however, and it is important to 3064ensure the `dlloader_exit' callback releases any resources claimed 3065during the initialisation phase. 3066 3067libltdl provides the following functions for writing your own module 3068loaders: 3069 3070 -- Function: int lt_dlloader_add (lt_dlloader *PLACE, 3071 lt_user_dlloader *DLLOADER, const char *LOADER_NAME) 3072 Add a new module loader to the list of all loaders, either as the 3073 last loader (if PLACE is `NULL'), else immediately before the 3074 loader passed as PLACE. LOADER_NAME will be returned by 3075 `lt_dlloader_name' if it is subsequently passed a newly registered 3076 loader. These LOADER_NAMEs must be unique, or 3077 `lt_dlloader_remove' and `lt_dlloader_find' cannot work. Returns 0 3078 for success. 3079 3080 { 3081 /* Make myloader be the last one. */ 3082 if (lt_dlloader_add (NULL, myloader) != 0) 3083 perror (lt_dlerror ()); 3084 } 3085 3086 -- Function: int lt_dlloader_remove (const char *LOADER_NAME) 3087 Remove the loader identified by the unique name, LOADER_NAME. 3088 Before this can succeed, all modules opened by the named loader 3089 must have been closed. Returns 0 for success, otherwise an error 3090 message can be obtained from `lt_dlerror'. 3091 3092 { 3093 /* Remove myloader. */ 3094 if (lt_dlloader_remove ("myloader") != 0) 3095 perror (lt_dlerror ()); 3096 } 3097 3098 -- Function: lt_dlloader * lt_dlloader_next (lt_dlloader *PLACE) 3099 Iterate over the module loaders, returning the first loader if 3100 PLACE is `NULL', and the next one on subsequent calls. The handle 3101 is for use with `lt_dlloader_add'. 3102 3103 { 3104 /* Make myloader be the first one. */ 3105 if (lt_dlloader_add (lt_dlloader_next (NULL), myloader) != 0) 3106 return ERROR; 3107 } 3108 3109 -- Function: lt_dlloader * lt_dlloader_find (const char *LOADER_NAME) 3110 Return the first loader with a matching LOADER_NAME identifier, or 3111 else `NULL', if the identifier is not found. 3112 3113 The identifiers which may be used by libltdl itself, if the host 3114 architecture supports them are "dlopen"(1), "dld" and "dlpreload". 3115 3116 { 3117 /* Add a user loader as the next module loader to be tried if 3118 the standard dlopen loader were to fail when lt_dlopening. */ 3119 if (lt_dlloader_add (lt_dlloader_find ("dlopen"), myloader) != 0) 3120 return ERROR; 3121 } 3122 3123 -- Function: const char * lt_dlloader_name (lt_dlloader *PLACE) 3124 Return the identifying name of PLACE, as obtained from 3125 `lt_dlloader_next' or `lt_dlloader_find'. If this function fails, 3126 it will return `NULL' and set an error for retrieval with 3127 `lt_dlerror'. 3128 3129 -- Function: lt_user_data * lt_dlloader_data (lt_dlloader *PLACE) 3130 Return the address of the `dlloader_data' of PLACE, as obtained 3131 from `lt_dlloader_next' or `lt_dlloader_find'. If this function 3132 fails, it will return `NULL' and set an error for retrieval with 3133 `lt_dlerror'. 3134 313510.5.1 Error handling within user module loaders 3136------------------------------------------------ 3137 3138 -- Function: int lt_dladderror (const char *DIAGNOSTIC) 3139 This function allows you to integrate your own error messages into 3140 `lt_dlerror'. Pass in a suitable diagnostic message for return by 3141 `lt_dlerror', and an error identifier for use with `lt_dlseterror' 3142 is returned. 3143 3144 If the allocation of an identifier fails, this function returns -1. 3145 3146 int myerror = lt_dladderror ("Doh!"); 3147 if (myerror < 0) 3148 perror (lt_dlerror ()); 3149 3150 -- Function: int lt_dlseterror (int ERRORCODE) 3151 When writing your own module loaders, you should use this function 3152 to raise errors so that they are propogated through the 3153 `lt_dlerror' interface. All of the standard errors used by libltdl 3154 are declared in `ltdl.h', or you can add more of your own with 3155 `lt_dladderror'. This function returns 0 on success. 3156 3157 if (lt_dlseterror (LTDL_ERROR_NO_MEMORY) != 0) 3158 perror (lt_dlerror ()); 3159 3160---------- Footnotes ---------- 3161 3162 (1) This is used for the host dependent module loading API - 3163`shl_load' and `LoadLibrary' for example 3164 3165 3166File: libtool.info, Node: Distributing libltdl, Prev: Module loaders for libltdl, Up: Using libltdl 3167 316810.6 How to distribute libltdl with your package 3169================================================ 3170 3171Even though libltdl is installed together with libtool, you may wish to 3172include libltdl in the distribution of your package, for the convenience 3173of users of your package that don't have libtool or libltdl installed. 3174In this case, you must decide whether to manually add the `ltdl' 3175objects to your package, or else which flavor of libltdl you want to 3176use: a convenience library or an installable libtool library. 3177 3178 The most simplistic way to add `libltdl' to your package is to copy 3179the source files, `ltdl.c' and `ltdl.h', to a source directory within 3180your package and to build and link them along with the rest of your 3181sources. To help you do this, the m4 macros for autoconf are available 3182in `ltdl.m4'. You must ensure that they are available in `aclocal.m4' 3183before you run Autoconf - by appending the contents of `ltdl.m4' to 3184`acinclude.m4', if you are using automake, or to `aclocal.m4' if you 3185are not. Having made the macros available, you must add a call to the 3186`AC_LIB_LTDL' macro to your package's `configure.in' to perform the 3187configure time checks required to build `ltdl.o' correctly. This 3188method has problems if you then try to link the package binaries with 3189an installed libltdl, or a library which depends on libltdl: you may 3190have problems with duplicate symbol definitions. 3191 3192 One advantage of the convenience library is that it is not 3193installed, so the fact that you use libltdl will not be apparent to the 3194user, and it will not overwrite a pre-installed version of libltdl a 3195user might have. On the other hand, if you want to upgrade libltdl for 3196any reason (e.g. a bugfix) you'll have to recompile your package 3197instead of just replacing an installed version of libltdl. However, if 3198your programs or libraries are linked with other libraries that use 3199such a pre-installed version of libltdl, you may get linker errors or 3200run-time crashes. Another problem is that you cannot link the 3201convenience library into more than one libtool library, then link a 3202single program with these libraries, because you may get duplicate 3203symbols. In general you can safely use the convenience library in 3204programs which don't depend on other libraries that might use libltdl 3205too. In order to enable this flavor of libltdl, you should add the 3206line `AC_LIBLTDL_CONVENIENCE' to your `configure.in', _before_ 3207`AC_PROG_LIBTOOL'. 3208 3209 In order to select the installable version of libltdl, you should 3210add a call of the macro `AC_LIBLTDL_INSTALLABLE' to your `configure.in' 3211_before_ `AC_PROG_LIBTOOL'. This macro will check whether libltdl is 3212already installed and, if not, request the libltdl embedded in your 3213package to be built and installed. Note, however, that no version 3214checking is performed. The user may override the test and determine 3215that the libltdl embedded must be installed, regardless of the 3216existence of another version, using the configure switch 3217`--enable-ltdl-install'. 3218 3219 In order to embed libltdl into your package, just add `--ltdl' to 3220the `libtoolize' command line. It will copy the libltdl sources to a 3221subdirectory `libltdl' in your package. Both macros accept an optional 3222argument to specify the location of the `libltdl' directory. By the 3223default both macros assume that it is `${top_srcdir}/libltdl'. 3224 3225 Whatever macro you use, it is up to you to ensure that your 3226`configure.in' will configure libltdl, using `AC_CONFIG_SUBDIRS', and 3227that your `Makefile's will start sub-makes within libltdl's directory, 3228using automake's SUBDIRS, for example. Both macros define the shell 3229variables LIBLTDL, to the link flag that you should use to link with 3230libltdl, and LTDLINCL, to the preprocessor flag that you should use to 3231compile with programs that include `ltdl.h'. It is up to you to use 3232`AC_SUBST' to ensure that this variable will be available in 3233`Makefile's, or add them to variables that are `AC_SUBST'ed by default, 3234such as LIBS and CPPFLAGS. Also note that you should not include 3235`libltdl/Makefile' in the list of files to be configured from your 3236toplevel `configure.in'; this is done by `libltdl/configure.ac'. 3237 3238 If you're using the convenience libltdl, LIBLTDL will be the 3239pathname for the convenience version of libltdl and LTDLINCL will be 3240`-I' followed by the directory that contains libltdl, both starting 3241with `${top_builddir}/' or `${top_srcdir}/', respectively. 3242 3243 If you request an installed version of libltdl and one is found(1), 3244LIBLTDL will be set to `-lltdl' and LTDLINCL will be empty (which is 3245just a blind assumption that `ltdl.h' is somewhere in the include path 3246if libltdl is in the library path). If an installable version of 3247libltdl must be built, its pathname, starting with `${top_builddir}/', 3248will be stored in LIBLTDL, and LTDLINCL will be set just like in the 3249case of convenience library. 3250 3251 So, when you want to link a program with libltdl, be it a 3252convenience, installed or installable library, just compile with 3253`$(LTDLINCL)' and link it with `$(LIBLTDL)', using libtool. 3254 3255 You should probably also add `AC_LIBTOOL_DLOPEN' to your 3256`configure.in' _before_ `AC_PROG_LIBTOOL', otherwise libtool will 3257assume no dlopening mechanism is supported, and revert to dlpreopening, 3258which is probably not what you want. 3259 3260 Avoid using the `-static' or `-all-static' switches when linking 3261programs with libltdl. This will not work on all platforms, because 3262the dlopening functions may not be available for static linking. 3263 3264 The following example shows you how to embed the convenience libltdl 3265in your package. In order to use the installable variant just replace 3266`AC_LIBLTDL_CONVENIENCE' with `AC_LIBLTDL_INSTALLABLE'. We assume that 3267libltdl was embedded using `libtoolize --ltdl'. 3268 3269 configure.in: 3270 ... 3271 dnl Enable building of the convenience library 3272 dnl and set LIBLTDL accordingly 3273 AC_LIBLTDL_CONVENIENCE 3274 dnl Check for dlopen support 3275 AC_LIBTOOL_DLOPEN 3276 dnl Configure libtool 3277 AC_PROG_LIBTOOL 3278 dnl Configure libltdl 3279 AC_CONFIG_SUBDIRS(libltdl) 3280 ... 3281 3282 Makefile.am: 3283 ... 3284 SUBDIRS = libltdl 3285 3286 INCLUDES = $(LTDLINCL) 3287 3288 myprog_LDFLAGS = -export-dynamic 3289 # The quotes around -dlopen below fool automake <= 1.4 into accepting it 3290 myprog_LDADD = $(LIBLTDL) "-dlopen" self "-dlopen" foo1.la 3291 myprog_DEPENDENCIES = $(LIBLTDL) foo1.la 3292 ... 3293 3294 ---------- Footnotes ---------- 3295 3296 (1) Even if libltdl is installed, `AC_LIBLTDL_INSTALLABLE' may fail 3297to detect it, if libltdl depends on symbols provided by libraries other 3298than the C library. In this case, it will needlessly build and install 3299libltdl. 3300 3301 3302File: libtool.info, Node: Other languages, Next: Troubleshooting, Prev: Using libltdl, Up: Top 3303 330411 Using libtool with other languages 3305************************************* 3306 3307Libtool was first implemented in order to add support for writing shared 3308libraries in the C language. However, over time, libtool is being 3309integrated with other languages, so that programmers are free to reap 3310the benefits of shared libraries in their favorite programming language. 3311 3312 This chapter describes how libtool interacts with other languages, 3313and what special considerations you need to make if you do not use C. 3314 3315* Menu: 3316 3317* C++ libraries:: 3318 3319 3320File: libtool.info, Node: C++ libraries, Up: Other languages 3321 332211.1 Writing libraries for C++ 3323============================== 3324 3325Creating libraries of C++ code should be a fairly straightforward 3326process, because its object files differ from C ones in only three ways: 3327 3328 1. Because of name mangling, C++ libraries are only usable by the C++ 3329 compiler that created them. This decision was made by the 3330 designers of C++ in order to protect users from conflicting 3331 implementations of features such as constructors, exception 3332 handling, and RTTI. 3333 3334 2. On some systems, the C++ compiler must take special actions for the 3335 dynamic linker to run dynamic (i.e., run-time) initializers. This 3336 means that we should not call `ld' directly to link such 3337 libraries, and we should use the C++ compiler instead. 3338 3339 3. C++ compilers will link some Standard C++ library in by default, 3340 but libtool does not know which are these libraries, so it cannot 3341 even run the inter-library dependence analyzer to check how to 3342 link it in. Therefore, running `ld' to link a C++ program or 3343 library is deemed to fail. 3344 3345 Because of these three issues, Libtool has been designed to always 3346use the C++ compiler to compile and link C++ programs and libraries. In 3347some instances the `main()' function of a program must also be compiled 3348with the C++ compiler for static C++ objects to be properly initialized. 3349 3350 3351File: libtool.info, Node: Troubleshooting, Next: Maintaining, Prev: Other languages, Up: Top 3352 335312 Troubleshooting 3354****************** 3355 3356Libtool is under constant development, changing to remain up-to-date 3357with modern operating systems. If libtool doesn't work the way you 3358think it should on your platform, you should read this chapter to help 3359determine what the problem is, and how to resolve it. 3360 3361* Menu: 3362 3363* Libtool test suite:: Libtool's self-tests. 3364* Reporting bugs:: How to report problems with libtool. 3365 3366 3367File: libtool.info, Node: Libtool test suite, Next: Reporting bugs, Up: Troubleshooting 3368 336912.1 The libtool test suite 3370=========================== 3371 3372Libtool comes with its own set of programs that test its capabilities, 3373and report obvious bugs in the libtool program. These tests, too, are 3374constantly evolving, based on past problems with libtool, and known 3375deficiencies in other operating systems. 3376 3377 As described in the `INSTALL' file, you may run `make check' after 3378you have built libtool (possibly before you install it) in order to 3379make sure that it meets basic functional requirements. 3380 3381* Menu: 3382 3383* Test descriptions:: The contents of the test suite. 3384* When tests fail:: What to do when a test fails. 3385 3386 3387File: libtool.info, Node: Test descriptions, Next: When tests fail, Up: Libtool test suite 3388 338912.1.1 Description of test suite 3390-------------------------------- 3391 3392Here is a list of the current programs in the test suite, and what they 3393test for: 3394 3395`cdemo-conf.test' 3396`cdemo-exec.test' 3397`cdemo-make.test' 3398`cdemo-static.test' 3399`cdemo-shared.test' 3400 These programs check to see that the `cdemo' subdirectory of the 3401 libtool distribution can be configured and built correctly. 3402 3403 The `cdemo' subdirectory contains a demonstration of libtool 3404 convenience libraries, a mechanism that allows build-time static 3405 libraries to be created, in a way that their components can be 3406 later linked into programs or other libraries, even shared ones. 3407 3408 The tests `cdemo-make.test' and `cdemo-exec.test' are executed 3409 three times, under three different libtool configurations: 3410 `cdemo-conf.test' configures `cdemo/libtool' to build both static 3411 and shared libraries (the default for platforms that support 3412 both), `cdemo-static.test' builds only static libraries 3413 (`--disable-shared'), and `cdemo-shared.test' builds only shared 3414 libraries (`--disable-static'). 3415 3416`demo-conf.test' 3417`demo-exec.test' 3418`demo-inst.test' 3419`demo-make.test' 3420`demo-unst.test' 3421`demo-static.test' 3422`demo-shared.test' 3423`demo-nofast.test' 3424`demo-pic.test' 3425`demo-nopic.test' 3426 These programs check to see that the `demo' subdirectory of the 3427 libtool distribution can be configured, built, installed, and 3428 uninstalled correctly. 3429 3430 The `demo' subdirectory contains a demonstration of a trivial 3431 package that uses libtool. The tests `demo-make.test', 3432 `demo-exec.test', `demo-inst.test' and `demo-unst.test' are 3433 executed four times, under four different libtool configurations: 3434 `demo-conf.test' configures `demo/libtool' to build both static 3435 and shared libraries, `demo-static.test' builds only static 3436 libraries (`--disable-shared'), and `demo-shared.test' builds only 3437 shared libraries (`--disable-static'). `demo-nofast.test' 3438 configures `demo/libtool' to disable the fast-install mode 3439 (`--enable-fast-install=no'). `demo-pic.test' configures 3440 `demo/libtool' to prefer building PIC code (`--with-pic'), 3441 `demo-nopic.test' to prefer non-PIC code (`--without-pic'). 3442 3443`deplibs.test' 3444 Many systems cannot link static libraries into shared libraries. 3445 libtool uses a `deplibs_check_method' to prevent such cases. This 3446 tests checks whether libtool's `deplibs_check_method' works 3447 properly. 3448 3449`hardcode.test' 3450 On all systems with shared libraries, the location of the library 3451 can be encoded in executables that are linked against it *note 3452 Linking executables::. This test checks the conditions under 3453 which your system linker hardcodes the library location, and 3454 guarantees that they correspond to libtool's own notion of how 3455 your linker behaves. 3456 3457`build-relink.test' 3458 Checks whether variable SHLIBPATH_OVERRIDES_RUNPATH is properly 3459 set. If the test fails and VERBOSE is set, it will indicate what 3460 the variable should have been set to. 3461 3462`noinst-link.test' 3463 Checks whether libtool will not try to link with a previously 3464 installed version of a library when it should be linking with a 3465 just-built one. 3466 3467`depdemo-conf.test' 3468`depdemo-exec.test' 3469`depdemo-inst.test' 3470`depdemo-make.test' 3471`depdemo-unst.test' 3472`depdemo-static.test' 3473`depdemo-shared.test' 3474`depdemo-nofast.test' 3475 These programs check to see that the `depdemo' subdirectory of the 3476 libtool distribution can be configured, built, installed, and 3477 uninstalled correctly. 3478 3479 The `depdemo' subdirectory contains a demonstration of 3480 inter-library dependencies with libtool. The test programs link 3481 some interdependent libraries. 3482 3483 The tests `depdemo-make.test', `depdemo-exec.test', 3484 `depdemo-inst.test' and `depdemo-unst.test' are executed four 3485 times, under four different libtool configurations: 3486 `depdemo-conf.test' configures `depdemo/libtool' to build both 3487 static and shared libraries, `depdemo-static.test' builds only 3488 static libraries (`--disable-shared'), and `depdemo-shared.test' 3489 builds only shared libraries (`--disable-static'). 3490 `depdemo-nofast.test' configures `depdemo/libtool' to disable the 3491 fast-install mode (`--enable-fast-install=no'. 3492 3493`mdemo-conf.test' 3494`mdemo-exec.test' 3495`mdemo-inst.test' 3496`mdemo-make.test' 3497`mdemo-unst.test' 3498`mdemo-static.test' 3499`mdemo-shared.test' 3500 These programs check to see that the `mdemo' subdirectory of the 3501 libtool distribution can be configured, built, installed, and 3502 uninstalled correctly. 3503 3504 The `mdemo' subdirectory contains a demonstration of a package that 3505 uses libtool and the system independent dlopen wrapper `libltdl' to 3506 load modules. The library `libltdl' provides a dlopen wrapper for 3507 various platforms (Linux, Solaris, HP/UX etc.) including support 3508 for dlpreopened modules (*note Dlpreopening::). 3509 3510 The tests `mdemo-make.test', `mdemo-exec.test', `mdemo-inst.test' 3511 and `mdemo-unst.test' are executed three times, under three 3512 different libtool configurations: `mdemo-conf.test' configures 3513 `mdemo/libtool' to build both static and shared libraries, 3514 `mdemo-static.test' builds only static libraries 3515 (`--disable-shared'), and `mdemo-shared.test' builds only shared 3516 libraries (`--disable-static'). 3517 3518`dryrun.test' 3519 This test checks whether libtool's `--dry-run' mode works properly. 3520 3521`assign.test' 3522 Checks whether we don't put break or continue on the same line as 3523 an assignment in the libtool script. 3524 3525`link.test' 3526 This test guarantees that linking directly against a non-libtool 3527 static library works properly. 3528 3529`link-2.test' 3530 This test makes sure that files ending in `.lo' are never linked 3531 directly into a program file. 3532 3533`nomode.test' 3534 Check whether we can actually get help for libtool. 3535 3536`quote.test' 3537 This program checks libtool's metacharacter quoting. 3538 3539`sh.test' 3540 Checks whether a `test' command was forgotten in libtool. 3541 3542`suffix.test' 3543 When other programming languages are used with libtool (*note 3544 Other languages::), the source files may end in suffixes other 3545 than `.c'. This test validates that libtool can handle suffixes 3546 for all the file types that it supports, and that it fails when 3547 the suffix is invalid. 3548 3549 3550 3551File: libtool.info, Node: When tests fail, Prev: Test descriptions, Up: Libtool test suite 3552 355312.1.2 When tests fail 3554---------------------- 3555 3556Each of the above tests are designed to produce no output when they are 3557run via `make check'. The exit status of each program tells the 3558`Makefile' whether or not the test succeeded. 3559 3560 If a test fails, it means that there is either a programming error in 3561libtool, or in the test program itself. 3562 3563 To investigate a particular test, you may run it directly, as you 3564would a normal program. When the test is invoked in this way, it 3565produces output which may be useful in determining what the problem is. 3566 3567 Another way to have the test programs produce output is to set the 3568VERBOSE environment variable to `yes' before running them. For 3569example, `env VERBOSE=yes make check' runs all the tests, and has each 3570of them display debugging information. 3571 3572 3573File: libtool.info, Node: Reporting bugs, Prev: Libtool test suite, Up: Troubleshooting 3574 357512.2 Reporting bugs 3576=================== 3577 3578If you think you have discovered a bug in libtool, you should think 3579twice: the libtool maintainer is notorious for passing the buck (or 3580maybe that should be "passing the bug"). Libtool was invented to fix 3581known deficiencies in shared library implementations, so, in a way, most 3582of the bugs in libtool are actually bugs in other operating systems. 3583However, the libtool maintainer would definitely be happy to add support 3584for somebody else's buggy operating system. [I wish there was a good 3585way to do winking smiley-faces in Texinfo.] 3586 3587 Genuine bugs in libtool include problems with shell script 3588portability, documentation errors, and failures in the test suite 3589(*note Libtool test suite::). 3590 3591 First, check the documentation and help screens to make sure that the 3592behaviour you think is a problem is not already mentioned as a feature. 3593 3594 Then, you should read the Emacs guide to reporting bugs (*note 3595Reporting Bugs: (emacs)Bugs.). Some of the details listed there are 3596specific to Emacs, but the principle behind them is a general one. 3597 3598 Finally, send a bug report to the libtool bug reporting address 3599<bug-libtool@gnu.org> with any appropriate _facts_, such as test suite 3600output (*note When tests fail::), all the details needed to reproduce 3601the bug, and a brief description of why you think the behaviour is a 3602bug. Be sure to include the word "libtool" in the subject line, as 3603well as the version number you are using (which can be found by typing 3604`libtool --version'). 3605 3606 3607File: libtool.info, Node: Maintaining, Next: GNU Free Documentation License, Prev: Troubleshooting, Up: Top 3608 360913 Maintenance notes for libtool 3610******************************** 3611 3612This chapter contains information that the libtool maintainer finds 3613important. It will be of no use to you unless you are considering 3614porting libtool to new systems, or writing your own libtool. 3615 3616* Menu: 3617 3618* New ports:: How to port libtool to new systems. 3619* Tested platforms:: When libtool was last tested. 3620* Platform quirks:: Information about different library systems. 3621* libtool script contents:: Configuration information that libtool uses. 3622* Cheap tricks:: Making libtool maintainership easier. 3623 3624 3625File: libtool.info, Node: New ports, Next: Tested platforms, Up: Maintaining 3626 362713.1 Porting libtool to new systems 3628=================================== 3629 3630Before you embark on porting libtool to an unsupported system, it is 3631worthwhile to send e-mail to the libtool mailing list 3632<libtool@gnu.org>, to make sure that you are not duplicating existing 3633work. 3634 3635 If you find that any porting documentation is missing, please 3636complain! Complaints with patches and improvements to the 3637documentation, or to libtool itself, are more than welcome. 3638 3639* Menu: 3640 3641* Information sources:: Where to find relevant documentation 3642* Porting inter-library dependencies:: Implementation details explained 3643 3644 3645File: libtool.info, Node: Information sources, Next: Porting inter-library dependencies, Up: New ports 3646 364713.1.1 Information sources 3648-------------------------- 3649 3650Once it is clear that a new port is necessary, you'll generally need the 3651following information: 3652 3653canonical system name 3654 You need the output of `config.guess' for this system, so that you 3655 can make changes to the libtool configuration process without 3656 affecting other systems. 3657 3658man pages for `ld' and `cc' 3659 These generally describe what flags are used to generate PIC, to 3660 create shared libraries, and to link against only static 3661 libraries. You may need to follow some cross references to find 3662 the information that is required. 3663 3664man pages for `ld.so', `rtld', or equivalent 3665 These are a valuable resource for understanding how shared 3666 libraries are loaded on the system. 3667 3668man page for `ldconfig', or equivalent 3669 This page usually describes how to install shared libraries. 3670 3671output from `ls -l /lib /usr/lib' 3672 This shows the naming convention for shared libraries on the 3673 system, including which names should be symbolic links. 3674 3675any additional documentation 3676 Some systems have special documentation on how to build and install 3677 shared libraries. 3678 3679 If you know how to program the Bourne shell, then you can complete 3680the port yourself; otherwise, you'll have to find somebody with the 3681relevant skills who will do the work. People on the libtool mailing 3682list are usually willing to volunteer to help you with new ports, so 3683you can send the information to them. 3684 3685 To do the port yourself, you'll definitely need to modify the 3686`libtool.m4' macros in order to make platform-specific changes to the 3687configuration process. You should search that file for the `PORTME' 3688keyword, which will give you some hints on what you'll need to change. 3689In general, all that is involved is modifying the appropriate 3690configuration variables (*note libtool script contents::). 3691 3692 Your best bet is to find an already-supported system that is similar 3693to yours, and make your changes based on that. In some cases, however, 3694your system will differ significantly from every other supported system, 3695and it may be necessary to add new configuration variables, and modify 3696the `ltmain.in' script accordingly. Be sure to write to the mailing 3697list before you make changes to `ltmain.in', since they may have advice 3698on the most effective way of accomplishing what you want. 3699 3700 3701File: libtool.info, Node: Porting inter-library dependencies, Prev: Information sources, Up: New ports 3702 370313.1.2 Porting inter-library dependencies support 3704------------------------------------------------- 3705 3706Since version 1.2c, libtool has re-introduced the ability to do 3707inter-library dependency on some platforms, thanks to a patch by Toshio 3708Kuratomi <badger@prtr-13.ucsc.edu>. Here's a shortened version of the 3709message that contained his patch: 3710 3711 The basic architecture is this: in `libtool.m4', the person who 3712writes libtool makes sure `$deplibs' is included in `$archive_cmds' 3713somewhere and also sets the variable `$deplibs_check_method', and maybe 3714`$file_magic_cmd' when `deplibs_check_method' is file_magic. 3715 3716 `deplibs_check_method' can be one of five things: 3717`file_magic [REGEX]' 3718 looks in the library link path for libraries that have the right 3719 libname. Then it runs `$file_magic_cmd' on the library and checks 3720 for a match against the extended regular expression REGEX. When 3721 FILE_MAGIC_TEST_FILE is set by `libtool.m4', it is used as an 3722 argument to `$file_magic_cmd' in order to verify whether the 3723 regular expression matches its output, and warn the user otherwise. 3724 3725`test_compile' 3726 just checks whether it is possible to link a program out of a list 3727 of libraries, and checks which of those are listed in the output of 3728 `ldd'. It is currently unused, and will probably be dropped in the 3729 future. 3730 3731`pass_all' 3732 will pass everything without any checking. This may work on 3733 platforms in which code is position-independent by default and 3734 inter-library dependencies are properly supported by the dynamic 3735 linker, for example, on DEC OSF/1 3 and 4. 3736 3737`none' 3738 It causes deplibs to be reassigned deplibs="". That way 3739 `archive_cmds' can contain deplibs on all platforms, but not have 3740 deplibs used unless needed. 3741 3742`unknown' 3743 is the default for all systems unless overridden in `libtool.m4'. 3744 It is the same as `none', but it documents that we really don't 3745 know what the correct value should be, and we welcome patches that 3746 improve it. 3747 3748 Then in `ltmain.in' we have the real workhorse: a little 3749initialization and postprocessing (to setup/release variables for use 3750with eval echo libname_spec etc.) and a case statement that decides 3751which method is being used. This is the real code... I wish I could 3752condense it a little more, but I don't think I can without function 3753calls. I've mostly optimized it (moved things out of loops, etc) but 3754there is probably some fat left. I thought I should stop while I was 3755ahead, work on whatever bugs you discover, etc before thinking about 3756more than obvious optimizations. 3757 3758 3759File: libtool.info, Node: Tested platforms, Next: Platform quirks, Prev: New ports, Up: Maintaining 3760 376113.2 Tested platforms 3762===================== 3763 3764This table describes when libtool was last known to be tested on 3765platforms where it claims to support shared libraries: 3766 3767 ------------------------------------------------------- 3768 canonical host name compiler libtool results 3769 (tools versions) release 3770 ------------------------------------------------------- 3771 alpha-dec-osf5.1 cc 1.3e ok (1.910) 3772 alpha-dec-osf4.0f gcc 1.3e ok (1.910) 3773 alpha-dec-osf4.0f cc 1.3e ok (1.910) 3774 alpha-dec-osf3.2 gcc 0.8 ok 3775 alpha-dec-osf3.2 cc 0.8 ok 3776 alpha-dec-osf2.1 gcc 1.2f NS 3777 alpha*-unknown-linux-gnu gcc 1.3b ok 3778 (egcs-1.1.2, GNU ld 2.9.1.0.23) 3779 hppa2.0w-hp-hpux11.00 cc 1.2f ok 3780 hppa2.0-hp-hpux10.20 cc 1.3.2 ok 3781 hppa1.1-hp-hpux10.20 gcc 1.2f ok 3782 hppa1.1-hp-hpux10.20 cc 1.3c ok (1.821) 3783 hppa1.1-hp-hpux10.10 gcc 1.2f ok 3784 hppa1.1-hp-hpux10.10 cc 1.2f ok 3785 hppa1.1-hp-hpux9.07 gcc 1.2f ok 3786 hppa1.1-hp-hpux9.07 cc 1.2f ok 3787 hppa1.1-hp-hpux9.05 gcc 1.2f ok 3788 hppa1.1-hp-hpux9.05 cc 1.2f ok 3789 hppa1.1-hp-hpux9.01 gcc 1.2f ok 3790 hppa1.1-hp-hpux9.01 cc 1.2f ok 3791 i*86-*-beos gcc 1.2f ok 3792 i*86-*-bsdi4.0.1 gcc 1.3c ok 3793 (gcc-2.7.2.1) 3794 i*86-*-bsdi4.0 gcc 1.2f ok 3795 i*86-*-bsdi3.1 gcc 1.2e NS 3796 i*86-*-bsdi3.0 gcc 1.2e NS 3797 i*86-*-bsdi2.1 gcc 1.2e NS 3798 i*86-pc-cygwin gcc 1.3b NS 3799 (egcs-1.1 stock b20.1 compiler) 3800 i*86-*-dguxR4.20MU01 gcc 1.2 ok 3801 i*86-*-freebsd4.3 gcc 1.3e ok (1.912) 3802 i*86-*-freebsdelf4.0 gcc 1.3c ok 3803 (egcs-1.1.2) 3804 i*86-*-freebsdelf3.2 gcc 1.3c ok 3805 (gcc-2.7.2.1) 3806 i*86-*-freebsdelf3.1 gcc 1.3c ok 3807 (gcc-2.7.2.1) 3808 i*86-*-freebsdelf3.0 gcc 1.3c ok 3809 i*86-*-freebsd3.0 gcc 1.2e ok 3810 i*86-*-freebsd2.2.8 gcc 1.3c ok 3811 (gcc-2.7.2.1) 3812 i*86-*-freebsd2.2.6 gcc 1.3b ok 3813 (egcs-1.1 & gcc-2.7.2.1, native ld) 3814 i*86-*-freebsd2.1.5 gcc 0.5 ok 3815 i*86-*-netbsd1.5 gcc 1.3e ok (1.901) 3816 (egcs-1.1.2) 3817 i*86-*-netbsd1.4 gcc 1.3c ok 3818 (egcs-1.1.1) 3819 i*86-*-netbsd1.4.3A gcc 1.3e ok (1.901) 3820 i*86-*-netbsd1.3.3 gcc 1.3c ok 3821 (gcc-2.7.2.2+myc2) 3822 i*86-*-netbsd1.3.2 gcc 1.2e ok 3823 i*86-*-netbsd1.3I gcc 1.2e ok 3824 (egcs 1.1?) 3825 i*86-*-netbsd1.2 gcc 0.9g ok 3826 i*86-*-linux-gnu gcc 1.3e ok (1.901) 3827 (Red Hat 7.0, gcc "2.96") 3828 i*86-*-linux-gnu gcc 1.3e ok (1.911) 3829 (SuSE 7.0, gcc 2.95.2) 3830 i*86-*-linux-gnulibc1 gcc 1.2f ok 3831 i*86-*-openbsd2.5 gcc 1.3c ok 3832 (gcc-2.8.1) 3833 i*86-*-openbsd2.4 gcc 1.3c ok 3834 (gcc-2.8.1) 3835 i*86-*-solaris2.7 gcc 1.3b ok 3836 (egcs-1.1.2, native ld) 3837 i*86-*-solaris2.6 gcc 1.2f ok 3838 i*86-*-solaris2.5.1 gcc 1.2f ok 3839 i*86-ncr-sysv4.3.03 gcc 1.2f ok 3840 i*86-ncr-sysv4.3.03 cc 1.2e ok 3841 (cc -Hnocopyr) 3842 i*86-pc-sco3.2v5.0.5 cc 1.3c ok 3843 i*86-pc-sco3.2v5.0.5 gcc 1.3c ok 3844 (gcc 95q4c) 3845 i*86-pc-sco3.2v5.0.5 gcc 1.3c ok 3846 (egcs-1.1.2) 3847 i*86-sco-sysv5uw7.1.1 gcc 1.3e ok (1.901) 3848 (gcc-2.95.2, SCO linker) 3849 i*86-UnixWare7.1.0-sysv5 cc 1.3c ok 3850 i*86-UnixWare7.1.0-sysv5 gcc 1.3c ok 3851 (egcs-1.1.1) 3852 m68k-next-nextstep3 gcc 1.2f NS 3853 m68k-sun-sunos4.1.1 gcc 1.2f NS 3854 (gcc-2.5.7) 3855 m88k-dg-dguxR4.12TMU01 gcc 1.2 ok 3856 m88k-motorola-sysv4 gcc 1.3 ok 3857 (egcs-1.1.2) 3858 mips-sgi-irix6.5 gcc 1.2f ok 3859 (gcc-2.8.1) 3860 mips-sgi-irix6.4 gcc 1.2f ok 3861 mips-sgi-irix6.3 gcc 1.3b ok 3862 (egcs-1.1.2, native ld) 3863 mips-sgi-irix6.3 cc 1.3b ok 3864 (cc 7.0) 3865 mips-sgi-irix6.2 gcc 1.2f ok 3866 mips-sgi-irix6.2 cc 0.9 ok 3867 mips-sgi-irix5.3 gcc 1.2f ok 3868 (egcs-1.1.1) 3869 mips-sgi-irix5.3 gcc 1.2f NS 3870 (gcc-2.6.3) 3871 mips-sgi-irix5.3 cc 0.8 ok 3872 mips-sgi-irix5.2 gcc 1.3b ok 3873 (egcs-1.1.2, native ld) 3874 mips-sgi-irix5.2 cc 1.3b ok 3875 (cc 3.18) 3876 mips-sni-sysv4 cc 1.3.5 ok 3877 (Siemens C-compiler) 3878 mips-sni-sysv4 gcc 1.3.5 ok 3879 (gcc-2.7.2.3, GNU assembler 2.8.1, native ld) 3880 mipsel-unknown-openbsd2.1 gcc 1.0 ok 3881 powerpc-apple-darwin6.4 gcc 1.5 ok 3882 (apple dev tools released 12/2002) 3883 powerpc-ibm-aix4.3.1.0 gcc 1.2f ok 3884 (egcs-1.1.1) 3885 powerpc-ibm-aix4.2.1.0 gcc 1.2f ok 3886 (egcs-1.1.1) 3887 powerpc-ibm-aix4.1.5.0 gcc 1.2f ok 3888 (egcs-1.1.1) 3889 powerpc-ibm-aix4.1.5.0 gcc 1.2f NS 3890 (gcc-2.8.1) 3891 powerpc-ibm-aix4.1.4.0 gcc 1.0 ok 3892 powerpc-ibm-aix4.1.4.0 xlc 1.0i ok 3893 rs6000-ibm-aix4.1.5.0 gcc 1.2f ok 3894 (gcc-2.7.2) 3895 rs6000-ibm-aix4.1.4.0 gcc 1.2f ok 3896 (gcc-2.7.2) 3897 rs6000-ibm-aix3.2.5 gcc 1.0i ok 3898 rs6000-ibm-aix3.2.5 xlc 1.0i ok 3899 sparc-sun-solaris2.8 gcc 1.3e ok (1.913) 3900 (gcc-2.95.3 & native ld) 3901 sparc-sun-solaris2.7 gcc 1.3e ok (1.913) 3902 (gcc-2.95.3 & native ld) 3903 sparc-sun-solaris2.6 gcc 1.3e ok (1.913) 3904 (gcc-2.95.3 & native ld) 3905 sparc-sun-solaris2.5.1 gcc 1.3e ok (1.911) 3906 sparc-sun-solaris2.5 gcc 1.3b ok 3907 (egcs-1.1.2, GNU ld 2.9.1 & native ld) 3908 sparc-sun-solaris2.5 cc 1.3b ok 3909 (SC 3.0.1) 3910 sparc-sun-solaris2.4 gcc 1.0a ok 3911 sparc-sun-solaris2.4 cc 1.0a ok 3912 sparc-sun-solaris2.3 gcc 1.2f ok 3913 sparc-sun-sunos4.1.4 gcc 1.2f ok 3914 sparc-sun-sunos4.1.4 cc 1.0f ok 3915 sparc-sun-sunos4.1.3_U1 gcc 1.2f ok 3916 sparc-sun-sunos4.1.3C gcc 1.2f ok 3917 sparc-sun-sunos4.1.3 gcc 1.3b ok 3918 (egcs-1.1.2, GNU ld 2.9.1 & native ld) 3919 sparc-sun-sunos4.1.3 cc 1.3b ok 3920 sparc-unknown-bsdi4.0 gcc 1.2c ok 3921 sparc-unknown-linux-gnulibc1 gcc 1.2f ok 3922 sparc-unknown-linux-gnu gcc 1.3b ok 3923 (egcs-1.1.2, GNU ld 2.9.1.0.23) 3924 sparc64-unknown-linux-gnu gcc 1.2f ok 3925 3926 Notes: 3927 - "ok" means "all tests passed". 3928 - "NS" means "Not Shared", but OK for static libraries 3929 3930 Note: The vendor-distributed HP-UX `sed'(1) programs are horribly 3931broken, and cannot handle libtool's requirements, so users may report 3932unusual problems. There is no workaround except to install a working 3933`sed' (such as GNU `sed') on these systems. 3934 3935 Note: The vendor-distributed NCR MP-RAS `cc' programs emits 3936copyright on standard error that confuse tests on size of 3937`conftest.err'. The workaround is to specify `CC' when run `configure' 3938with `CC='cc -Hnocopyr''. 3939 3940 3941File: libtool.info, Node: Platform quirks, Next: libtool script contents, Prev: Tested platforms, Up: Maintaining 3942 394313.3 Platform quirks 3944==================== 3945 3946This section is dedicated to the sanity of the libtool maintainers. It 3947describes the programs that libtool uses, how they vary from system to 3948system, and how to test for them. 3949 3950 Because libtool is a shell script, it can be difficult to understand 3951just by reading it from top to bottom. This section helps show why 3952libtool does things a certain way. Combined with the scripts 3953themselves, you should have a better sense of how to improve libtool, or 3954write your own. 3955 3956* Menu: 3957 3958* References:: Finding more information. 3959* Compilers:: Creating object files from source files. 3960* Reloadable objects:: Binding object files together. 3961* Multiple dependencies:: Removing duplicate dependent libraries. 3962* Archivers:: Programs that create static archives. 3963 3964 3965File: libtool.info, Node: References, Next: Compilers, Up: Platform quirks 3966 396713.3.1 References 3968----------------- 3969 3970The following is a list of valuable documentation references: 3971 3972 * SGI's IRIX Manual Pages, which can be found at 3973 `http://techpubs.sgi.com/cgi-bin/infosrch.cgi?cmd=browse&db=man'. 3974 3975 * Sun's free service area 3976 (`http://www.sun.com/service/online/free.html') and documentation 3977 server (`http://docs.sun.com/'). 3978 3979 * Compaq's Tru64 UNIX online documentation is at 3980 (`http://tru64unix.compaq.com/faqs/publications/pub_page/doc_list.html') 3981 with C++ documentation at 3982 (`http://tru64unix.compaq.com/cplus/docs/index.htm'). 3983 3984 * Hewlett-Packard has online documentation at 3985 (`http://docs.hp.com/index.html'). 3986 3987 * IBM has online documentation at 3988 (`http://www.rs6000.ibm.com/resource/aix_resource/Pubs/'). 3989 3990 3991File: libtool.info, Node: Compilers, Next: Reloadable objects, Prev: References, Up: Platform quirks 3992 399313.3.2 Compilers 3994---------------- 3995 3996The only compiler characteristics that affect libtool are the flags 3997needed (if any) to generate PIC objects. In general, if a C compiler 3998supports certain PIC flags, then any derivative compilers support the 3999same flags. Until there are some noteworthy exceptions to this rule, 4000this section will document only C compilers. 4001 4002 The following C compilers have standard command line options, 4003regardless of the platform: 4004 4005`gcc' 4006 This is the GNU C compiler, which is also the system compiler for 4007 many free operating systems (FreeBSD, GNU/Hurd, GNU/Linux, Lites, 4008 NetBSD, and OpenBSD, to name a few). 4009 4010 The `-fpic' or `-fPIC' flags can be used to generate 4011 position-independent code. `-fPIC' is guaranteed to generate 4012 working code, but the code is slower on m68k, m88k, and Sparc 4013 chips. However, using `-fpic' on those chips imposes arbitrary 4014 size limits on the shared libraries. 4015 4016 The rest of this subsection lists compilers by the operating system 4017that they are bundled with: 4018 4019`aix3*' 4020`aix4*' 4021 Most AIX compilers have no PIC flags, since AIX (with the 4022 exception of AIX for IA-64) runs on PowerPC and RS/6000 chips. (1) 4023 4024`hpux10*' 4025 Use `+Z' to generate PIC. 4026 4027`osf3*' 4028 Digital/UNIX 3.x does not have PIC flags, at least not on the 4029 PowerPC platform. 4030 4031`solaris2*' 4032 Use `-KPIC' to generate PIC. 4033 4034`sunos4*' 4035 Use `-PIC' to generate PIC. 4036 4037 ---------- Footnotes ---------- 4038 4039 (1) All code compiled for the PowerPC and RS/6000 chips 4040(`powerpc-*-*', `powerpcle-*-*', and `rs6000-*-*') is 4041position-independent, regardless of the operating system or compiler 4042suite. So, "regular objects" can be used to build shared libraries on 4043these systems and no special PIC compiler flags are required. 4044 4045 4046File: libtool.info, Node: Reloadable objects, Next: Multiple dependencies, Prev: Compilers, Up: Platform quirks 4047 404813.3.3 Reloadable objects 4049------------------------- 4050 4051On all known systems, a reloadable object can be created by running `ld 4052-r -o OUTPUT.o INPUT1.o INPUT2.o'. This reloadable object may be 4053treated as exactly equivalent to other objects. 4054 4055 4056File: libtool.info, Node: Multiple dependencies, Next: Archivers, Prev: Reloadable objects, Up: Platform quirks 4057 405813.3.4 Multiple dependencies 4059---------------------------- 4060 4061On most modern platforms the order that dependent libraries are listed 4062has no effect on object generation. In theory, there are platforms 4063which require libraries which provide missing symbols to other libraries 4064to listed after those libraries whose symbols they provide. 4065 4066 Particularly, if a pair of static archives each resolve some of the 4067other's symbols, it might be necessary to list one of those archives 4068both before and after the other one. Libtool does not currently cope 4069with this situation well, since duplicate libraries are removed from 4070the link line by default. Libtool provides the command line option 4071`--preserve-dup-deps' to preserve all duplicate dependencies in cases 4072where it is necessary. 4073 4074 4075File: libtool.info, Node: Archivers, Prev: Multiple dependencies, Up: Platform quirks 4076 407713.3.5 Archivers 4078---------------- 4079 4080On all known systems, building a static library can be accomplished by 4081running `ar cru libNAME.a OBJ1.o OBJ2.o ...', where the `.a' file is 4082the output library, and each `.o' file is an object file. 4083 4084 On all known systems, if there is a program named `ranlib', then it 4085must be used to "bless" the created library before linking against it, 4086with the `ranlib libNAME.a' command. Some systems, like Irix, use the 4087`ar ts' command, instead. 4088 4089 4090File: libtool.info, Node: libtool script contents, Next: Cheap tricks, Prev: Platform quirks, Up: Maintaining 4091 409213.4 `libtool' script contents 4093============================== 4094 4095Since version 1.4, the `libtool' script is generated by `configure' 4096(*note Configuring::). In earlier versions, `configure' achieved this 4097by calling a helper script called `ltconfig'. From libtool version 0.7 4098to 1.0, this script simply set shell variables, then sourced the 4099libtool backend, `ltmain.sh'. `ltconfig' from libtool version 1.1 4100through 1.3 inlined the contents of `ltmain.sh' into the generated 4101`libtool', which improved performance on many systems. The tests that 4102`ltconfig' used to perform are now kept in `libtool.m4' where thay can 4103be written using Autoconf. This has the runtime performance benefits 4104of inlined `ltmain.sh', _and_ improves the build time a little while 4105considerably easing the amount of raw shell code that used to need 4106maintaining. 4107 4108 The convention used for naming variables which hold shell commands 4109for delayed evaluation, is to use the suffix `_cmd' where a single line 4110of valid shell script is needed, and the suffix `_cmds' where multiple 4111lines of shell script *may* be delayed for later evaluation. By 4112convention, `_cmds' variables delimit the evaluation units with the `~' 4113character where necessary. 4114 4115 Here is a listing of each of the configuration variables, and how 4116they are used within `ltmain.sh' (*note Configuring::): 4117 4118 -- Variable: AR 4119 The name of the system library archiver. 4120 4121 -- Variable: CC 4122 The name of the C compiler used to configure libtool. 4123 4124 -- Variable: LD 4125 The name of the linker that libtool should use internally for 4126 reloadable linking and possibly shared libraries. 4127 4128 -- Variable: NM 4129 The name of a BSD-compatible `nm' program, which produces listings 4130 of global symbols in one the following formats: 4131 4132 ADDRESS C GLOBAL-VARIABLE-NAME 4133 ADDRESS D GLOBAL-VARIABLE-NAME 4134 ADDRESS T GLOBAL-FUNCTION-NAME 4135 4136 -- Variable: RANLIB 4137 Set to the name of the ranlib program, if any. 4138 4139 -- Variable: allow_undefined_flag 4140 The flag that is used by `archive_cmds' in order to declare that 4141 there will be unresolved symbols in the resulting shared library. 4142 Empty, if no such flag is required. Set to `unsupported' if there 4143 is no way to generate a shared library with references to symbols 4144 that aren't defined in that library. 4145 4146 -- Variable: always_export_symbols 4147 Whether libtool should automatically generate a list of exported 4148 symbols using EXPORT_SYMBOLS_CMDS before linking an archive. Set 4149 to `yes' or `no'. Default is `no'. 4150 4151 -- Variable: archive_cmds 4152 -- Variable: archive_expsym_cmds 4153 -- Variable: old_archive_cmds 4154 Commands used to create shared libraries, shared libraries with 4155 `-export-symbols' and static libraries, respectively. 4156 4157 -- Variable: old_archive_from_new_cmds 4158 If the shared library depends on a static library, 4159 `old_archive_from_new_cmds' contains the commands used to create 4160 that static library. If this variable is not empty, 4161 `old_archive_cmds' is not used. 4162 4163 -- Variable: old_archive_from_expsyms_cmds 4164 If a static library must be created from the export symbol list in 4165 order to correctly link with a shared library, 4166 `old_archive_from_expsyms_cmds' contains the commands needed to 4167 create that static library. When these commands are executed, the 4168 variable SONAME contains the name of the shared library in 4169 question, and the $OBJDIR/$NEWLIB contains the path of the static 4170 library these commands should build. After executing these 4171 commands, libtool will proceed to link against $OBJDIR/$NEWLIB 4172 instead of SONAME. 4173 4174 -- Variable: build_libtool_libs 4175 Whether libtool should build shared libraries on this system. Set 4176 to `yes' or `no'. 4177 4178 -- Variable: build_old_libs 4179 Whether libtool should build static libraries on this system. Set 4180 to `yes' or `no'. 4181 4182 -- Variable: compiler_c_o 4183 Whether the compiler supports the `-c' and `-o' options 4184 simultaneously. Set to `yes' or `no'. 4185 4186 -- Variable: compiler_o_lo 4187 Whether the compiler supports compiling directly to a ".lo" file, 4188 i.e whether object files do not have to have the suffix ".o". Set 4189 to `yes' or `no'. 4190 4191 -- Variable: dlopen_support 4192 Whether `dlopen' is supported on the platform. Set to `yes' or 4193 `no'. 4194 4195 -- Variable: dlopen_self 4196 Whether it is possible to `dlopen' the executable itself. Set to 4197 `yes' or `no'. 4198 4199 -- Variable: dlopen_self_static 4200 Whether it is possible to `dlopen' the executable itself, when it 4201 is linked statically (`-all-static'). Set to `yes' or `no'. 4202 4203 -- Variable: echo 4204 An `echo' program which does not interpret backslashes as an 4205 escape character. 4206 4207 -- Variable: exclude_expsyms 4208 List of symbols that should not be listed in the preloaded symbols. 4209 4210 -- Variable: export_dynamic_flag_spec 4211 Compiler link flag that allows a dlopened shared library to 4212 reference symbols that are defined in the program. 4213 4214 -- Variable: export_symbols_cmds 4215 Commands to extract exported symbols from LIBOBJS to the file 4216 EXPORT_SYMBOLS. 4217 4218 -- Variable: extract_expsyms_cmds 4219 Commands to extract the exported symbols list from a shared 4220 library. These commands are executed if there is no file 4221 $OBJDIR/$SONAME-DEF, and should write the names of the exported 4222 symbols to that file, for the use of 4223 `old_archive_from_expsyms_cmds'. 4224 4225 -- Variable: fast_install 4226 Determines whether libtool will privilege the installer or the 4227 developer. The assumption is that installers will seldom run 4228 programs in the build tree, and the developer will seldom install. 4229 This is only meaningful on platforms in which 4230 SHLIBPATH_OVERRIDES_RUNPATH is not `yes', so FAST_INSTALL will be 4231 set to `needless' in this case. If FAST_INSTALL set to `yes', 4232 libtool will create programs that search for installed libraries, 4233 and, if a program is run in the build tree, a new copy will be 4234 linked on-demand to use the yet-to-be-installed libraries. If set 4235 to `no', libtool will create programs that use the 4236 yet-to-be-installed libraries, and will link a new copy of the 4237 program at install time. The default value is `yes' or 4238 `needless', depending on platform and configuration flags, and it 4239 can be turned from `yes' to `no' with the configure flag 4240 `--disable-fast-install'. 4241 4242 -- Variable: finish_cmds 4243 Commands to tell the dynamic linker how to find shared libraries 4244 in a specific directory. 4245 4246 -- Variable: finish_eval 4247 Same as FINISH_CMDS, except the commands are not displayed. 4248 4249 -- Variable: fix_srcfile_path 4250 Expression to fix the shell variable $srcfile for the compiler. 4251 4252 -- Variable: global_symbol_pipe 4253 A pipeline that takes the output of NM, and produces a listing of 4254 raw symbols followed by their C names. For example: 4255 4256 $ eval "$NM progname | $global_symbol_pipe" 4257 D SYMBOL1 C-SYMBOL1 4258 T SYMBOL2 C-SYMBOL2 4259 C SYMBOL3 C-SYMBOL3 4260 ... 4261 $ 4262 4263 The first column contains the symbol type (used to tell data from 4264 code on some platforms), but its meaning is system dependent. 4265 4266 -- Variable: global_symbol_to_cdecl 4267 A pipeline that translates the output of GLOBAL_SYMBOL_PIPE into 4268 proper C declarations. On platforms whose linkers differentiate 4269 code from data, such as HP/UX, data symbols will be declared as 4270 such, and code symbols will be declared as functions. On 4271 platforms that don't care, everything is assumed to be data. 4272 4273 -- Variable: hardcode_action 4274 Either `immediate' or `relink', depending on whether shared 4275 library paths can be hardcoded into executables before they are 4276 installed, or if they need to be relinked. 4277 4278 -- Variable: hardcode_direct 4279 Set to `yes' or `no', depending on whether the linker hardcodes 4280 directories if a library is directly specified on the command line 4281 (such as `DIR/libNAME.a') when HARDCODE_LIBDIR_FLAG_SPEC is 4282 specified. 4283 4284 -- Variable: hardcode_into_libs 4285 Whether the platform supports hardcoding of run-paths into 4286 libraries. If enabled, linking of programs will be much simpler 4287 but libraries will need to be relinked during installation. Set 4288 to `yes' or `no'. 4289 4290 -- Variable: hardcode_libdir_flag_spec 4291 Flag to hardcode a LIBDIR variable into a binary, so that the 4292 dynamic linker searches LIBDIR for shared libraries at runtime. 4293 If it is empty, libtool will try to use some other hardcoding 4294 mechanism. 4295 4296 -- Variable: hardcode_libdir_separator 4297 If the compiler only accepts a single HARDCODE_LIBDIR_FLAG, then 4298 this variable contains the string that should separate multiple 4299 arguments to that flag. 4300 4301 -- Variable: hardcode_minus_L 4302 Set to `yes' or `no', depending on whether the linker hardcodes 4303 directories specified by `-L' flags into the resulting executable 4304 when HARDCODE_LIBDIR_FLAG_SPEC is specified. 4305 4306 -- Variable: hardcode_shlibpath_var 4307 Set to `yes' or `no', depending on whether the linker hardcodes 4308 directories by writing the contents of `$shlibpath_var' into the 4309 resulting executable when HARDCODE_LIBDIR_FLAG_SPEC is specified. 4310 Set to `unsupported' if directories specified by `$shlibpath_var' 4311 are searched at run time, but not at link time. 4312 4313 -- Variable: host 4314 -- Variable: host_alias 4315 For information purposes, set to the specified and canonical names 4316 of the system that libtool was configured for. 4317 4318 -- Variable: include_expsyms 4319 List of symbols that must always be exported when using 4320 EXPORT_SYMBOLS. 4321 4322 -- Variable: libext 4323 The standard old archive suffix (normally "a"). 4324 4325 -- Variable: libname_spec 4326 The format of a library name prefix. On all Unix systems, static 4327 libraries are called `libNAME.a', but on some systems (such as 4328 OS/2 or MS-DOS), the library is just called `NAME.a'. 4329 4330 -- Variable: library_names_spec 4331 A list of shared library names. The first is the name of the file, 4332 the rest are symbolic links to the file. The name in the list is 4333 the file name that the linker finds when given `-lNAME'. 4334 4335 -- Variable: link_all_deplibs 4336 Whether libtool must link a program against all its dependency 4337 libraries. Set to `yes' or `no'. Default is `unknown', which is 4338 a synonym for `yes'. 4339 4340 -- Variable: link_static_flag 4341 Linker flag (passed through the C compiler) used to prevent dynamic 4342 linking. 4343 4344 -- Variable: need_lib_prefix 4345 Whether libtool should automatically prefix module names with 4346 'lib'. Set to `yes' or `no'. By default, it is `unknown', which 4347 means the same as `yes', but documents that we are not really sure 4348 about it. `yes' means that it is possible both to `dlopen' and to 4349 link against a library without 'lib' prefix, i.e. it requires 4350 HARDCODE_DIRECT to be `yes'. 4351 4352 -- Variable: need_version 4353 Whether versioning is required for libraries, i.e. whether the 4354 dynamic linker requires a version suffix for all libraries. Set 4355 to `yes' or `no'. By default, it is `unknown', which means the 4356 same as `yes', but documents that we are not really sure about it. 4357 4358 -- Variable: need_locks 4359 Whether files must be locked to prevent conflicts when compiling 4360 simultaneously. Set to `yes' or `no'. 4361 4362 -- Variable: no_builtin_flag 4363 Compiler flag to disable builtin functions that conflict with 4364 declaring external global symbols as `char'. 4365 4366 -- Variable: no_undefined_flag 4367 The flag that is used by `archive_cmds' in order to declare that 4368 there will be no unresolved symbols in the resulting shared 4369 library. Empty, if no such flag is required. 4370 4371 -- Variable: objdir 4372 The name of the directory that contains temporary libtool files. 4373 4374 -- Variable: objext 4375 The standard object file suffix (normally "o"). 4376 4377 -- Variable: pic_flag 4378 Any additional compiler flags for building library object files. 4379 4380 -- Variable: postinstall_cmds 4381 -- Variable: old_postinstall_cmds 4382 Commands run after installing a shared or static library, 4383 respectively. 4384 4385 -- Variable: postuninstall_cmds 4386 -- Variable: old_postuninstall_cmds 4387 Commands run after uninstalling a shared or static library, 4388 respectively. 4389 4390 -- Variable: reload_cmds 4391 -- Variable: reload_flag 4392 Commands to create a reloadable object. 4393 4394 -- Variable: runpath_var 4395 The environment variable that tells the linker which directories to 4396 hardcode in the resulting executable. 4397 4398 -- Variable: shlibpath_overrides_runpath 4399 Indicates whether it is possible to override the hard-coded library 4400 search path of a program with an environment variable. If this is 4401 set to no, libtool may have to create two copies of a program in 4402 the build tree, one to be installed and one to be run in the build 4403 tree only. When each of these copies is created depends on the 4404 value of `fast_install'. The default value is `unknown', which is 4405 equivalent to `no'. 4406 4407 -- Variable: shlibpath_var 4408 The environment variable that tells the dynamic linker where to 4409 find shared libraries. 4410 4411 -- Variable: soname_spec 4412 The name coded into shared libraries, if different from the real 4413 name of the file. 4414 4415 -- Variable: striplib 4416 -- Variable: old_striplib 4417 Command to strip a shared (`striplib') or static (`old_striplib') 4418 library, respectively. If these variables are empty, the strip 4419 flag in the install mode will be ignored for libraries (*note 4420 Install mode::). 4421 4422 -- Variable: sys_lib_dlsearch_path_spec 4423 Expression to get the run-time system library search path. 4424 Directories that appear in this list are never hard-coded into 4425 executables. 4426 4427 -- Variable: sys_lib_search_path_spec 4428 Expression to get the compile-time system library search path. 4429 This variable is used by libtool when it has to test whether a 4430 certain library is shared or static. The directories listed in 4431 SHLIBPATH_VAR are automatically appended to this list, every time 4432 libtool runs (i.e., not at configuration time), because some 4433 linkers use this variable to extend the library search path. 4434 Linker switches such as `-L' also augment the search path. 4435 4436 -- Variable: thread_safe_flag_spec 4437 Linker flag (passed through the C compiler) used to generate 4438 thread-safe libraries. 4439 4440 -- Variable: version_type 4441 The library version numbering type. One of `libtool', 4442 `freebsd-aout', `freebsd-elf', `irix', `linux', `osf', `sunos', 4443 `windows', or `none'. 4444 4445 -- Variable: whole_archive_flag_spec 4446 Compiler flag to generate shared objects from convenience archives. 4447 4448 -- Variable: wl 4449 The C compiler flag that allows libtool to pass a flag directly to 4450 the linker. Used as: `${wl}SOME-FLAG'. 4451 4452 Variables ending in `_cmds' or `_eval' contain a `~'-separated list 4453of commands that are `eval'ed one after another. If any of the 4454commands return a nonzero exit status, libtool generally exits with an 4455error message. 4456 4457 Variables ending in `_spec' are `eval'ed before being used by 4458libtool. 4459 4460 4461File: libtool.info, Node: Cheap tricks, Prev: libtool script contents, Up: Maintaining 4462 446313.5 Cheap tricks 4464================= 4465 4466Here are a few tricks that you can use in order to make maintainership 4467easier: 4468 4469 * When people report bugs, ask them to use the `--config', 4470 `--debug', or `--features' flags, if you think they will help you. 4471 These flags are there to help you get information directly, rather 4472 than having to trust second-hand observation. 4473 4474 * Rather than reconfiguring libtool every time I make a change to 4475 `ltmain.in', I keep a permanent `libtool' script in my PATH, which 4476 sources `ltmain.in' directly. 4477 4478 The following steps describe how to create such a script, where 4479 `/home/src/libtool' is the directory containing the libtool source 4480 tree, `/home/src/libtool/libtool' is a libtool script that has been 4481 configured for your platform, and `~/bin' is a directory in your 4482 PATH: 4483 4484 trick$ cd ~/bin 4485 trick$ sed '/^# ltmain\.sh/q' /home/src/libtool/libtool > libtool 4486 trick$ echo '. /home/src/libtool/ltmain.in' >> libtool 4487 trick$ chmod +x libtool 4488 trick$ libtool --version 4489 ltmain.sh (GNU @PACKAGE@) @VERSION@@TIMESTAMP@ 4490 trick$ 4491 4492 The output of the final `libtool --version' command shows that the 4493`ltmain.in' script is being used directly. Now, modify `~/bin/libtool' 4494or `/home/src/libtool/ltmain.in' directly in order to test new changes 4495without having to rerun `configure'. 4496 4497 4498File: libtool.info, Node: GNU Free Documentation License, Next: Index, Prev: Maintaining, Up: Top 4499 4500GNU Free Documentation License 4501****************************** 4502 4503 Version 1.1, March 2000 4504 4505 Copyright (C) 2000 Free Software Foundation, Inc. 4506 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA 4507 Everyone is permitted to copy and distribute verbatim copies 4508 of this license document, but changing it is not allowed. 4509 4510Preamble 4511======== 4512 4513The purpose of this License is to make a manual, textbook, or other 4514written document "free" in the sense of freedom: to assure everyone the 4515effective freedom to copy and redistribute it, with or without 4516modifying it, either commercially or noncommercially. Secondarily, 4517this License preserves for the author and publisher a way to get credit 4518for their work, while not being considered responsible for 4519modifications made by others. 4520 4521 This License is a kind of "copyleft", which means that derivative 4522works of the document must themselves be free in the same sense. It 4523complements the GNU General Public License, which is a copyleft license 4524designed for free software. 4525 4526 We have designed this License in order to use it for manuals for free 4527software, because free software needs free documentation: a free 4528program should come with manuals providing the same freedoms that the 4529software does. But this License is not limited to software manuals; it 4530can be used for any textual work, regardless of subject matter or 4531whether it is published as a printed book. We recommend this License 4532principally for works whose purpose is instruction or reference. 4533 4534APPLICABILITY AND DEFINITIONS 4535============================= 4536 4537This License applies to any manual or other work that contains a notice 4538placed by the copyright holder saying it can be distributed under the 4539terms of this License. The "Document", below, refers to any such 4540manual or work. Any member of the public is a licensee, and is 4541addressed as "you". 4542 4543 A "Modified Version" of the Document means any work containing the 4544Document or a portion of it, either copied verbatim, or with 4545modifications and/or translated into another language. 4546 4547 A "Secondary Section" is a named appendix or a front-matter section 4548of the Document that deals exclusively with the relationship of the 4549publishers or authors of the Document to the Document's overall subject 4550(or to related matters) and contains nothing that could fall directly 4551within that overall subject. (For example, if the Document is in part a 4552textbook of mathematics, a Secondary Section may not explain any 4553mathematics.) The relationship could be a matter of historical 4554connection with the subject or with related matters, or of legal, 4555commercial, philosophical, ethical or political position regarding them. 4556 4557 The "Invariant Sections" are certain Secondary Sections whose titles 4558are designated, as being those of Invariant Sections, in the notice 4559that says that the Document is released under this License. 4560 4561 The "Cover Texts" are certain short passages of text that are listed, 4562as Front-Cover Texts or Back-Cover Texts, in the notice that says that 4563the Document is released under this License. 4564 4565 A "Transparent" copy of the Document means a machine-readable copy, 4566represented in a format whose specification is available to the general 4567public, whose contents can be viewed and edited directly and 4568straightforwardly with generic text editors or (for images composed of 4569pixels) generic paint programs or (for drawings) some widely available 4570drawing editor, and that is suitable for input to text formatters or 4571for automatic translation to a variety of formats suitable for input to 4572text formatters. A copy made in an otherwise Transparent file format 4573whose markup has been designed to thwart or discourage subsequent 4574modification by readers is not Transparent. A copy that is not 4575"Transparent" is called "Opaque". 4576 4577 Examples of suitable formats for Transparent copies include plain 4578ASCII without markup, Texinfo input format, LaTeX input format, SGML or 4579XML using a publicly available DTD, and standard-conforming simple HTML 4580designed for human modification. Opaque formats include PostScript, 4581PDF, proprietary formats that can be read and edited only by 4582proprietary word processors, SGML or XML for which the DTD and/or 4583processing tools are not generally available, and the machine-generated 4584HTML produced by some word processors for output purposes only. 4585 4586 The "Title Page" means, for a printed book, the title page itself, 4587plus such following pages as are needed to hold, legibly, the material 4588this License requires to appear in the title page. For works in 4589formats which do not have any title page as such, "Title Page" means 4590the text near the most prominent appearance of the work's title, 4591preceding the beginning of the body of the text. 4592 4593VERBATIM COPYING 4594================ 4595 4596You may copy and distribute the Document in any medium, either 4597commercially or noncommercially, provided that this License, the 4598copyright notices, and the license notice saying this License applies 4599to the Document are reproduced in all copies, and that you add no other 4600conditions whatsoever to those of this License. You may not use 4601technical measures to obstruct or control the reading or further 4602copying of the copies you make or distribute. However, you may accept 4603compensation in exchange for copies. If you distribute a large enough 4604number of copies you must also follow the conditions in section 3. 4605 4606 You may also lend copies, under the same conditions stated above, and 4607you may publicly display copies. 4608 4609COPYING IN QUANTITY 4610=================== 4611 4612If you publish printed copies of the Document numbering more than 100, 4613and the Document's license notice requires Cover Texts, you must enclose 4614the copies in covers that carry, clearly and legibly, all these Cover 4615Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on 4616the back cover. Both covers must also clearly and legibly identify you 4617as the publisher of these copies. The front cover must present the 4618full title with all words of the title equally prominent and visible. 4619You may add other material on the covers in addition. Copying with 4620changes limited to the covers, as long as they preserve the title of 4621the Document and satisfy these conditions, can be treated as verbatim 4622copying in other respects. 4623 4624 If the required texts for either cover are too voluminous to fit 4625legibly, you should put the first ones listed (as many as fit 4626reasonably) on the actual cover, and continue the rest onto adjacent 4627pages. 4628 4629 If you publish or distribute Opaque copies of the Document numbering 4630more than 100, you must either include a machine-readable Transparent 4631copy along with each Opaque copy, or state in or with each Opaque copy 4632a publicly-accessible computer-network location containing a complete 4633Transparent copy of the Document, free of added material, which the 4634general network-using public has access to download anonymously at no 4635charge using public-standard network protocols. If you use the latter 4636option, you must take reasonably prudent steps, when you begin 4637distribution of Opaque copies in quantity, to ensure that this 4638Transparent copy will remain thus accessible at the stated location 4639until at least one year after the last time you distribute an Opaque 4640copy (directly or through your agents or retailers) of that edition to 4641the public. 4642 4643 It is requested, but not required, that you contact the authors of 4644the Document well before redistributing any large number of copies, to 4645give them a chance to provide you with an updated version of the 4646Document. 4647 4648MODIFICATIONS 4649============= 4650 4651You may copy and distribute a Modified Version of the Document under 4652the conditions of sections 2 and 3 above, provided that you release the 4653Modified Version under precisely this License, with the Modified 4654Version filling the role of the Document, thus licensing distribution 4655and modification of the Modified Version to whoever possesses a copy of 4656it. In addition, you must do these things in the Modified Version: 4657 4658 A. Use in the Title Page (and on the covers, if any) a title distinct 4659 from that of the Document, and from those of previous versions 4660 (which should, if there were any, be listed in the History section 4661 of the Document). You may use the same title as a previous version 4662 if the original publisher of that version gives permission. 4663 4664 B. List on the Title Page, as authors, one or more persons or 4665 entities responsible for authorship of the modifications in the 4666 Modified Version, together with at least five of the principal 4667 authors of the Document (all of its principal authors, if it has 4668 less than five). 4669 4670 C. State on the Title page the name of the publisher of the Modified 4671 Version, as the publisher. 4672 4673 D. Preserve all the copyright notices of the Document. 4674 4675 E. Add an appropriate copyright notice for your modifications 4676 adjacent to the other copyright notices. 4677 4678 F. Include, immediately after the copyright notices, a license notice 4679 giving the public permission to use the Modified Version under the 4680 terms of this License, in the form shown in the Addendum below. 4681 4682 G. Preserve in that license notice the full lists of Invariant 4683 Sections and required Cover Texts given in the Document's license 4684 notice. 4685 4686 H. Include an unaltered copy of this License. 4687 4688 I. Preserve the section entitled "History", and its title, and add to 4689 it an item stating at least the title, year, new authors, and 4690 publisher of the Modified Version as given on the Title Page. If 4691 there is no section entitled "History" in the Document, create one 4692 stating the title, year, authors, and publisher of the Document as 4693 given on its Title Page, then add an item describing the Modified 4694 Version as stated in the previous sentence. 4695 4696 J. Preserve the network location, if any, given in the Document for 4697 public access to a Transparent copy of the Document, and likewise 4698 the network locations given in the Document for previous versions 4699 it was based on. These may be placed in the "History" section. 4700 You may omit a network location for a work that was published at 4701 least four years before the Document itself, or if the original 4702 publisher of the version it refers to gives permission. 4703 4704 K. In any section entitled "Acknowledgements" or "Dedications", 4705 preserve the section's title, and preserve in the section all the 4706 substance and tone of each of the contributor acknowledgements 4707 and/or dedications given therein. 4708 4709 L. Preserve all the Invariant Sections of the Document, unaltered in 4710 their text and in their titles. Section numbers or the equivalent 4711 are not considered part of the section titles. 4712 4713 M. Delete any section entitled "Endorsements". Such a section may 4714 not be included in the Modified Version. 4715 4716 N. Do not retitle any existing section as "Endorsements" or to 4717 conflict in title with any Invariant Section. 4718 4719 If the Modified Version includes new front-matter sections or 4720appendices that qualify as Secondary Sections and contain no material 4721copied from the Document, you may at your option designate some or all 4722of these sections as invariant. To do this, add their titles to the 4723list of Invariant Sections in the Modified Version's license notice. 4724These titles must be distinct from any other section titles. 4725 4726 You may add a section entitled "Endorsements", provided it contains 4727nothing but endorsements of your Modified Version by various 4728parties-for example, statements of peer review or that the text has 4729been approved by an organization as the authoritative definition of a 4730standard. 4731 4732 You may add a passage of up to five words as a Front-Cover Text, and 4733a passage of up to 25 words as a Back-Cover Text, to the end of the list 4734of Cover Texts in the Modified Version. Only one passage of 4735Front-Cover Text and one of Back-Cover Text may be added by (or through 4736arrangements made by) any one entity. If the Document already includes 4737a cover text for the same cover, previously added by you or by 4738arrangement made by the same entity you are acting on behalf of, you 4739may not add another; but you may replace the old one, on explicit 4740permission from the previous publisher that added the old one. 4741 4742 The author(s) and publisher(s) of the Document do not by this License 4743give permission to use their names for publicity for or to assert or 4744imply endorsement of any Modified Version. 4745 4746COMBINING DOCUMENTS 4747=================== 4748 4749You may combine the Document with other documents released under this 4750License, under the terms defined in section 4 above for modified 4751versions, provided that you include in the combination all of the 4752Invariant Sections of all of the original documents, unmodified, and 4753list them all as Invariant Sections of your combined work in its 4754license notice. 4755 4756 The combined work need only contain one copy of this License, and 4757multiple identical Invariant Sections may be replaced with a single 4758copy. If there are multiple Invariant Sections with the same name but 4759different contents, make the title of each such section unique by 4760adding at the end of it, in parentheses, the name of the original 4761author or publisher of that section if known, or else a unique number. 4762Make the same adjustment to the section titles in the list of Invariant 4763Sections in the license notice of the combined work. 4764 4765 In the combination, you must combine any sections entitled "History" 4766in the various original documents, forming one section entitled 4767"History"; likewise combine any sections entitled "Acknowledgements", 4768and any sections entitled "Dedications". You must delete all sections 4769entitled "Endorsements." 4770 4771COLLECTIONS OF DOCUMENTS 4772======================== 4773 4774You may make a collection consisting of the Document and other documents 4775released under this License, and replace the individual copies of this 4776License in the various documents with a single copy that is included in 4777the collection, provided that you follow the rules of this License for 4778verbatim copying of each of the documents in all other respects. 4779 4780 You may extract a single document from such a collection, and 4781distribute it individually under this License, provided you insert a 4782copy of this License into the extracted document, and follow this 4783License in all other respects regarding verbatim copying of that 4784document. 4785 4786AGGREGATION WITH INDEPENDENT WORKS 4787================================== 4788 4789A compilation of the Document or its derivatives with other separate 4790and independent documents or works, in or on a volume of a storage or 4791distribution medium, does not as a whole count as a Modified Version of 4792the Document, provided no compilation copyright is claimed for the 4793compilation. Such a compilation is called an "aggregate", and this 4794License does not apply to the other self-contained works thus compiled 4795with the Document, on account of their being thus compiled, if they are 4796not themselves derivative works of the Document. 4797 4798 If the Cover Text requirement of section 3 is applicable to these 4799copies of the Document, then if the Document is less than one quarter 4800of the entire aggregate, the Document's Cover Texts may be placed on 4801covers that surround only the Document within the aggregate. Otherwise 4802they must appear on covers around the whole aggregate. 4803 4804TRANSLATION 4805=========== 4806 4807Translation is considered a kind of modification, so you may distribute 4808translations of the Document under the terms of section 4. Replacing 4809Invariant Sections with translations requires special permission from 4810their copyright holders, but you may include translations of some or 4811all Invariant Sections in addition to the original versions of these 4812Invariant Sections. You may include a translation of this License 4813provided that you also include the original English version of this 4814License. In case of a disagreement between the translation and the 4815original English version of this License, the original English version 4816will prevail. 4817 4818TERMINATION 4819=========== 4820 4821You may not copy, modify, sublicense, or distribute the Document except 4822as expressly provided for under this License. Any other attempt to 4823copy, modify, sublicense or distribute the Document is void, and will 4824automatically terminate your rights under this License. However, 4825parties who have received copies, or rights, from you under this 4826License will not have their licenses terminated so long as such parties 4827remain in full compliance. 4828 4829FUTURE REVISIONS OF THIS LICENSE 4830================================ 4831 4832The Free Software Foundation may publish new, revised versions of the 4833GNU Free Documentation License from time to time. Such new versions 4834will be similar in spirit to the present version, but may differ in 4835detail to address new problems or concerns. See 4836http://www.gnu.org/copyleft/. 4837 4838 Each version of the License is given a distinguishing version number. 4839If the Document specifies that a particular numbered version of this 4840License "or any later version" applies to it, you have the option of 4841following the terms and conditions either of that specified version or 4842of any later version that has been published (not as a draft) by the 4843Free Software Foundation. If the Document does not specify a version 4844number of this License, you may choose any version ever published (not 4845as a draft) by the Free Software Foundation. 4846 4847ADDENDUM: How to use this License for your documents 4848==================================================== 4849 4850To use this License in a document you have written, include a copy of 4851the License in the document and put the following copyright and license 4852notices just after the title page: 4853 4854 Copyright (c) YEAR YOUR NAME. 4855 Permission is granted to copy, distribute and/or modify this document 4856 under the terms of the GNU Free Documentation License, Version 1.1 4857 or any later version published by the Free Software Foundation; 4858 with the Invariant Sections being LIST THEIR TITLES, with the 4859 Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. 4860 A copy of the license is included in the section entitled "GNU 4861 Free Documentation License". 4862 4863 If you have no Invariant Sections, write "with no Invariant Sections" 4864instead of saying which ones are invariant. If you have no Front-Cover 4865Texts, write "no Front-Cover Texts" instead of "Front-Cover Texts being 4866LIST"; likewise for Back-Cover Texts. 4867 4868 If your document contains nontrivial examples of program code, we 4869recommend releasing these examples in parallel under your choice of 4870free software license, such as the GNU General Public License, to 4871permit their use in free software. 4872 4873 4874File: libtool.info, Node: Index, Prev: GNU Free Documentation License, Up: Top 4875 4876Index 4877***** 4878 4879[index] 4880* Menu: 4881 4882* .la files: Linking libraries. (line 24) 4883* .libs subdirectory: Linking libraries. (line 69) 4884* .lo files: Creating object files. 4885 (line 28) 4886* AC_CONFIG_AUX_DIR: Invoking libtoolize. (line 55) 4887* AC_DISABLE_FAST_INSTALL: AC_PROG_LIBTOOL. (line 87) 4888* AC_DISABLE_SHARED: AC_PROG_LIBTOOL. (line 93) 4889* AC_DISABLE_STATIC: AC_PROG_LIBTOOL. (line 99) 4890* AC_FUNC_ALLOCA: Autoconf .o macros. (line 13) 4891* AC_LIBTOOL_DLOPEN: AC_PROG_LIBTOOL. (line 67) 4892* AC_LIBTOOL_WIN32_DLL: AC_PROG_LIBTOOL. (line 73) 4893* AC_PROG_LIBTOOL: AC_PROG_LIBTOOL. (line 12) 4894* AC_REPLACE_FUNCS: Autoconf .o macros. (line 18) 4895* aclocal: AC_PROG_LIBTOOL. (line 162) 4896* allow_undefined_flag: libtool script contents. 4897 (line 51) 4898* always_export_symbols: libtool script contents. 4899 (line 58) 4900* AM_DISABLE_SHARED: AC_PROG_LIBTOOL. (line 94) 4901* AM_DISABLE_STATIC: AC_PROG_LIBTOOL. (line 100) 4902* AM_PROG_LIBTOOL: AC_PROG_LIBTOOL. (line 13) 4903* application-level dynamic linking <1>: Using libltdl. (line 6) 4904* application-level dynamic linking: Dlopened modules. (line 6) 4905* AR: libtool script contents. 4906 (line 30) 4907* ar: Linking libraries. (line 6) 4908* archive_cmds: libtool script contents. 4909 (line 63) 4910* archive_expsym_cmds: libtool script contents. 4911 (line 64) 4912* AS: AC_PROG_LIBTOOL. (line 159) 4913* assign.test: Test descriptions. (line 136) 4914* avoiding shared libraries: Static-only libraries. 4915 (line 6) 4916* bug reports: Reporting bugs. (line 6) 4917* buggy system linkers: Linking executables. (line 11) 4918* bugs, subtle ones caused by buggy linkers: Linking executables. 4919 (line 16) 4920* build-relink.test: Test descriptions. (line 72) 4921* build_libtool_libs: libtool script contents. 4922 (line 86) 4923* build_old_libs: libtool script contents. 4924 (line 90) 4925* C header files, portable: C header files. (line 6) 4926* C++, pitfalls: C++ libraries. (line 6) 4927* C++, using: Other languages. (line 6) 4928* C, not using: Other languages. (line 6) 4929* CC <1>: libtool script contents. 4930 (line 33) 4931* CC: AC_PROG_LIBTOOL. (line 108) 4932* cdemo-conf.test: Test descriptions. (line 14) 4933* cdemo-exec.test: Test descriptions. (line 14) 4934* cdemo-make.test: Test descriptions. (line 14) 4935* cdemo-shared.test: Test descriptions. (line 14) 4936* cdemo-static.test: Test descriptions. (line 14) 4937* CFLAGS: AC_PROG_LIBTOOL. (line 112) 4938* clean mode: Clean mode. (line 6) 4939* command options, libtool: Invoking libtool. (line 6) 4940* command options, libtoolize: Invoking libtoolize. (line 6) 4941* compile mode: Compile mode. (line 6) 4942* compiler_c_o: libtool script contents. 4943 (line 94) 4944* compiler_o_lo: libtool script contents. 4945 (line 98) 4946* compiling object files: Creating object files. 4947 (line 6) 4948* complexity of library systems: Postmortem. (line 11) 4949* config.guess: Distributing. (line 10) 4950* config.sub: Distributing. (line 13) 4951* configuring libtool: Configuring. (line 6) 4952* convenience libraries: Static libraries. (line 6) 4953* CPPFLAGS: AC_PROG_LIBTOOL. (line 118) 4954* debugging libraries: Static-only libraries. 4955 (line 6) 4956* definition of libraries: Libtool paradigm. (line 11) 4957* demo-conf.test: Test descriptions. (line 40) 4958* demo-exec.test: Test descriptions. (line 40) 4959* demo-inst.test: Test descriptions. (line 40) 4960* demo-make.test: Test descriptions. (line 40) 4961* demo-nofast.test: Test descriptions. (line 40) 4962* demo-nopic.test: Test descriptions. (line 40) 4963* demo-pic.test: Test descriptions. (line 40) 4964* demo-shared.test: Test descriptions. (line 40) 4965* demo-static.test: Test descriptions. (line 40) 4966* demo-unst.test: Test descriptions. (line 40) 4967* depdemo-conf.test: Test descriptions. (line 89) 4968* depdemo-exec.test: Test descriptions. (line 89) 4969* depdemo-inst.test: Test descriptions. (line 89) 4970* depdemo-make.test: Test descriptions. (line 89) 4971* depdemo-nofast.test: Test descriptions. (line 89) 4972* depdemo-shared.test: Test descriptions. (line 89) 4973* depdemo-static.test: Test descriptions. (line 89) 4974* depdemo-unst.test: Test descriptions. (line 89) 4975* dependencies between libraries: Inter-library dependencies. 4976 (line 6) 4977* dependency versioning: Versioning. (line 6) 4978* deplibs.test: Test descriptions. (line 58) 4979* deplibs_check_method: Porting inter-library dependencies. 4980 (line 6) 4981* design issues: Issues. (line 6) 4982* design of library interfaces: Library tips. (line 6) 4983* design philosophy: Motivation. (line 6) 4984* developing libraries: Static-only libraries. 4985 (line 6) 4986* dlclose <1>: Using libltdl. (line 6) 4987* dlclose: Dlopened modules. (line 6) 4988* dlerror: Using libltdl. (line 6) 4989* DLLTOOL: AC_PROG_LIBTOOL. (line 151) 4990* dlopen <1>: Using libltdl. (line 6) 4991* dlopen: Dlopened modules. (line 6) 4992* dlopen_self: libtool script contents. 4993 (line 107) 4994* dlopen_self_static: libtool script contents. 4995 (line 111) 4996* dlopen_support: libtool script contents. 4997 (line 103) 4998* dlopening modules <1>: Using libltdl. (line 6) 4999* dlopening modules: Dlopened modules. (line 6) 5000* dlopening, pitfalls: Dlopen issues. (line 6) 5001* dlsym <1>: Using libltdl. (line 6) 5002* dlsym: Dlopened modules. (line 6) 5003* double-compilation, avoiding: Static-only libraries. 5004 (line 6) 5005* dryrun.test: Test descriptions. (line 133) 5006* dynamic dependencies: Versioning. (line 6) 5007* dynamic linking, applications <1>: Using libltdl. (line 6) 5008* dynamic linking, applications: Dlopened modules. (line 6) 5009* dynamic modules, names: Finding the dlname. (line 6) 5010* echo: libtool script contents. 5011 (line 115) 5012* eliding shared libraries: Static-only libraries. 5013 (line 6) 5014* examples of using libtool: Using libtool. (line 6) 5015* exclude_expsyms: libtool script contents. 5016 (line 119) 5017* execute mode: Execute mode. (line 6) 5018* export_dynamic_flag_spec: libtool script contents. 5019 (line 122) 5020* export_symbols_cmds: libtool script contents. 5021 (line 126) 5022* extract_expsyms_cmds: libtool script contents. 5023 (line 130) 5024* failed tests: When tests fail. (line 6) 5025* fast_install: libtool script contents. 5026 (line 137) 5027* file_magic: Porting inter-library dependencies. 5028 (line 18) 5029* file_magic_cmd: Porting inter-library dependencies. 5030 (line 18) 5031* file_magic_test_file: Porting inter-library dependencies. 5032 (line 18) 5033* finish mode: Finish mode. (line 6) 5034* finish_cmds: libtool script contents. 5035 (line 154) 5036* finish_eval: libtool script contents. 5037 (line 158) 5038* fix_srcfile_path: libtool script contents. 5039 (line 161) 5040* formal versioning: Libtool versioning. (line 6) 5041* global functions: Library tips. (line 45) 5042* global_symbol_pipe: libtool script contents. 5043 (line 164) 5044* global_symbol_to_cdecl: libtool script contents. 5045 (line 178) 5046* hardcode.test: Test descriptions. (line 64) 5047* hardcode_action: libtool script contents. 5048 (line 185) 5049* hardcode_direct: libtool script contents. 5050 (line 190) 5051* hardcode_into_libs: libtool script contents. 5052 (line 196) 5053* hardcode_libdir_flag_spec: libtool script contents. 5054 (line 202) 5055* hardcode_libdir_separator: libtool script contents. 5056 (line 208) 5057* hardcode_minus_L: libtool script contents. 5058 (line 213) 5059* hardcode_shlibpath_var: libtool script contents. 5060 (line 218) 5061* header files: Library tips. (line 39) 5062* host: libtool script contents. 5063 (line 225) 5064* host_alias: libtool script contents. 5065 (line 226) 5066* implementation of libtool: libtool script contents. 5067 (line 6) 5068* include files, portable: C header files. (line 6) 5069* include_expsyms: libtool script contents. 5070 (line 230) 5071* install: Installing libraries. 5072 (line 19) 5073* install mode: Install mode. (line 6) 5074* install-sh: Distributing. (line 16) 5075* installation, finishing: Installing libraries. 5076 (line 54) 5077* inter-library dependencies: Inter-library dependencies. 5078 (line 6) 5079* inter-library dependency: Porting inter-library dependencies. 5080 (line 6) 5081* languages, non-C: Other languages. (line 6) 5082* LD <1>: libtool script contents. 5083 (line 36) 5084* LD: AC_PROG_LIBTOOL. (line 123) 5085* LDFLAGS: AC_PROG_LIBTOOL. (line 128) 5086* libext: libtool script contents. 5087 (line 234) 5088* libltdl: Using libltdl. (line 6) 5089* libname_spec: libtool script contents. 5090 (line 237) 5091* libraries, definition of: Libtool paradigm. (line 11) 5092* libraries, finishing installation: Installing libraries. 5093 (line 54) 5094* libraries, stripping: Installing libraries. 5095 (line 44) 5096* library interfaces: Interfaces. (line 6) 5097* library interfaces, design: Library tips. (line 6) 5098* library object file: Creating object files. 5099 (line 28) 5100* library_names_spec: libtool script contents. 5101 (line 242) 5102* LIBS: AC_PROG_LIBTOOL. (line 134) 5103* libtool: Invoking libtool. (line 6) 5104* libtool command options: Invoking libtool. (line 6) 5105* libtool examples: Using libtool. (line 6) 5106* libtool implementation: libtool script contents. 5107 (line 6) 5108* libtool libraries: Linking libraries. (line 24) 5109* libtool library versions: Libtool versioning. (line 6) 5110* libtool specifications: Motivation. (line 20) 5111* libtoolize: Invoking libtoolize. (line 6) 5112* libtoolize command options: Invoking libtoolize. (line 6) 5113* link mode: Link mode. (line 6) 5114* link-2.test: Test descriptions. (line 144) 5115* link.test: Test descriptions. (line 140) 5116* link_all_deplibs: libtool script contents. 5117 (line 247) 5118* link_static_flag: libtool script contents. 5119 (line 252) 5120* linking against installed libraries: Linking executables. (line 6) 5121* linking against uninstalled libraries: Linking executables. (line 25) 5122* linking with installed libtool libraries: Linking executables. 5123 (line 47) 5124* linking, partial: Link mode. (line 160) 5125* LN_S: AC_PROG_LIBTOOL. (line 146) 5126* lt_dladderror: Module loaders for libltdl. 5127 (line 199) 5128* lt_dladdsearchdir: Libltdl interface. (line 156) 5129* lt_dlcaller_get_data: User defined module data. 5130 (line 92) 5131* lt_dlcaller_id: User defined module data. 5132 (line 58) 5133* lt_dlcaller_register: User defined module data. 5134 (line 61) 5135* lt_dlcaller_set_data: User defined module data. 5136 (line 66) 5137* lt_dlclose: Libltdl interface. (line 112) 5138* lt_dlerror: Libltdl interface. (line 122) 5139* lt_dlexit: Libltdl interface. (line 53) 5140* lt_dlforeach: User defined module data. 5141 (line 34) 5142* lt_dlforeachfile: Libltdl interface. (line 176) 5143* lt_dlfree: Libltdl interface. (line 212) 5144* lt_dlgetinfo: User defined module data. 5145 (line 24) 5146* lt_dlgetsearchpath: Libltdl interface. (line 172) 5147* lt_dlhandle: Libltdl interface. (line 38) 5148* lt_dlhandle_next: User defined module data. 5149 (line 41) 5150* lt_dlinfo: User defined module data. 5151 (line 12) 5152* lt_dlinit: Libltdl interface. (line 48) 5153* lt_dlinsertsearchdir: Libltdl interface. (line 161) 5154* lt_dlisresident: Libltdl interface. (line 204) 5155* lt_dlloader: Module loaders for libltdl. 5156 (line 45) 5157* lt_dlloader_add: Module loaders for libltdl. 5158 (line 132) 5159* lt_dlloader_data: Module loaders for libltdl. 5160 (line 190) 5161* lt_dlloader_exit: Module loaders for libltdl. 5162 (line 86) 5163* lt_dlloader_find: Module loaders for libltdl. 5164 (line 170) 5165* lt_dlloader_name: Module loaders for libltdl. 5166 (line 184) 5167* lt_dlloader_next: Module loaders for libltdl. 5168 (line 159) 5169* lt_dlloader_remove: Module loaders for libltdl. 5170 (line 147) 5171* lt_dlmakeresident: Libltdl interface. (line 194) 5172* lt_dlmalloc: Libltdl interface. (line 210) 5173* lt_dlmutex_geterror: Thread Safety in libltdl. 5174 (line 34) 5175* lt_dlmutex_lock: Thread Safety in libltdl. 5176 (line 11) 5177* lt_dlmutex_register: Thread Safety in libltdl. 5178 (line 44) 5179* lt_dlmutex_seterror: Thread Safety in libltdl. 5180 (line 23) 5181* lt_dlmutex_unlock: Thread Safety in libltdl. 5182 (line 20) 5183* lt_dlopen: Libltdl interface. (line 59) 5184* lt_dlopenext: Libltdl interface. (line 96) 5185* lt_dlpreload: Libltdl interface. (line 128) 5186* lt_dlpreload_default: Libltdl interface. (line 134) 5187* lt_dlrealloc: Libltdl interface. (line 211) 5188* lt_dlseterror: Module loaders for libltdl. 5189 (line 211) 5190* lt_dlsetsearchpath: Libltdl interface. (line 167) 5191* lt_dlsym: Libltdl interface. (line 117) 5192* lt_dlsymlist <1>: Libltdl interface. (line 42) 5193* lt_dlsymlist: Dlpreopening. (line 41) 5194* lt_find_sym: Module loaders for libltdl. 5195 (line 79) 5196* lt_module: Module loaders for libltdl. 5197 (line 41) 5198* lt_module_close: Module loaders for libltdl. 5199 (line 72) 5200* lt_module_open: Module loaders for libltdl. 5201 (line 61) 5202* lt_preloaded_symbols: Dlpreopening. (line 46) 5203* lt_ptr: Libltdl interface. (line 35) 5204* lt_user_data: Module loaders for libltdl. 5205 (line 48) 5206* lt_user_dlloader: Module loaders for libltdl. 5207 (line 53) 5208* LTALLOCA: Autoconf .o macros. (line 13) 5209* LTDL_SET_PRELOADED_SYMBOLS: Libltdl interface. (line 144) 5210* LTLIBOBJS: Autoconf .o macros. (line 18) 5211* LTLIBRARIES: Using Automake. (line 6) 5212* ltmain.sh: Distributing. (line 19) 5213* Makefile: Makefile rules. (line 6) 5214* Makefile.am: Makefile rules. (line 6) 5215* Makefile.in: Makefile rules. (line 6) 5216* mdemo-conf.test: Test descriptions. (line 114) 5217* mdemo-exec.test: Test descriptions. (line 114) 5218* mdemo-inst.test: Test descriptions. (line 114) 5219* mdemo-make.test: Test descriptions. (line 114) 5220* mdemo-shared.test: Test descriptions. (line 114) 5221* mdemo-static.test: Test descriptions. (line 114) 5222* mdemo-unst.test: Test descriptions. (line 114) 5223* mode, clean: Clean mode. (line 6) 5224* mode, compile: Compile mode. (line 6) 5225* mode, execute: Execute mode. (line 6) 5226* mode, finish: Finish mode. (line 6) 5227* mode, install: Install mode. (line 6) 5228* mode, link: Link mode. (line 6) 5229* mode, uninstall: Uninstall mode. (line 6) 5230* modules, dynamic <1>: Using libltdl. (line 6) 5231* modules, dynamic: Dlopened modules. (line 6) 5232* motivation for writing libtool: Motivation. (line 6) 5233* names of dynamic modules: Finding the dlname. (line 6) 5234* need_lib_prefix: libtool script contents. 5235 (line 256) 5236* need_locks: libtool script contents. 5237 (line 270) 5238* need_version: libtool script contents. 5239 (line 264) 5240* NM <1>: libtool script contents. 5241 (line 40) 5242* NM: AC_PROG_LIBTOOL. (line 140) 5243* no_builtin_flag: libtool script contents. 5244 (line 274) 5245* no_undefined_flag: libtool script contents. 5246 (line 278) 5247* noinst-link.test: Test descriptions. (line 77) 5248* nomode.test: Test descriptions. (line 148) 5249* none: Porting inter-library dependencies. 5250 (line 38) 5251* objdir: libtool script contents. 5252 (line 283) 5253* OBJDUMP: AC_PROG_LIBTOOL. (line 155) 5254* object files, compiling: Creating object files. 5255 (line 6) 5256* object files, library: Creating object files. 5257 (line 28) 5258* objext: libtool script contents. 5259 (line 286) 5260* old_archive_cmds: libtool script contents. 5261 (line 65) 5262* old_archive_from_expsyms_cmds: libtool script contents. 5263 (line 75) 5264* old_archive_from_new_cmds: libtool script contents. 5265 (line 69) 5266* old_postinstall_cmds: libtool script contents. 5267 (line 293) 5268* old_postuninstall_cmds: libtool script contents. 5269 (line 298) 5270* old_striplib: libtool script contents. 5271 (line 328) 5272* opaque data types: Library tips. (line 28) 5273* options, libtool command: Invoking libtool. (line 6) 5274* options, libtoolize command: Invoking libtoolize. (line 6) 5275* other implementations, flaws in: Postmortem. (line 6) 5276* partial linking: Link mode. (line 160) 5277* pass_all: Porting inter-library dependencies. 5278 (line 32) 5279* PIC (position-independent code): Creating object files. 5280 (line 23) 5281* pic_flag: libtool script contents. 5282 (line 289) 5283* pitfalls using C++: C++ libraries. (line 6) 5284* pitfalls with dlopen: Dlopen issues. (line 6) 5285* portable C headers: C header files. (line 6) 5286* position-independent code: Creating object files. 5287 (line 23) 5288* postinstall_cmds: libtool script contents. 5289 (line 292) 5290* postinstallation: Installing libraries. 5291 (line 54) 5292* postuninstall_cmds: libtool script contents. 5293 (line 297) 5294* problem reports: Reporting bugs. (line 6) 5295* problems, blaming somebody else for: Troubleshooting. (line 6) 5296* problems, solving: Troubleshooting. (line 6) 5297* program wrapper scripts: Linking executables. (line 75) 5298* quote.test: Test descriptions. (line 151) 5299* RANLIB <1>: libtool script contents. 5300 (line 48) 5301* RANLIB: AC_PROG_LIBTOOL. (line 143) 5302* ranlib: Linking libraries. (line 12) 5303* reload_cmds: libtool script contents. 5304 (line 302) 5305* reload_flag: libtool script contents. 5306 (line 303) 5307* renaming interface functions: Library tips. (line 21) 5308* reporting bugs: Reporting bugs. (line 6) 5309* reusability of library systems: Postmortem. (line 6) 5310* runpath_var: libtool script contents. 5311 (line 306) 5312* saving time: Static-only libraries. 5313 (line 6) 5314* security problems with buggy linkers: Linking executables. (line 16) 5315* sh.test: Test descriptions. (line 154) 5316* shared libraries, not using: Static-only libraries. 5317 (line 6) 5318* shared library versions: Versioning. (line 6) 5319* shl_load <1>: Using libltdl. (line 6) 5320* shl_load: Dlopened modules. (line 6) 5321* shlibpath_overrides_runpath: libtool script contents. 5322 (line 310) 5323* shlibpath_var: libtool script contents. 5324 (line 319) 5325* solving problems: Troubleshooting. (line 6) 5326* soname_spec: libtool script contents. 5327 (line 323) 5328* specifications for libtool: Motivation. (line 20) 5329* standalone binaries: Static libraries. (line 61) 5330* static linking: Static libraries. (line 6) 5331* strip: Installing libraries. 5332 (line 6) 5333* striplib: libtool script contents. 5334 (line 327) 5335* stripping libraries: Installing libraries. 5336 (line 44) 5337* su: Installing libraries. 5338 (line 9) 5339* suffix.test: Test descriptions. (line 157) 5340* sys_lib_dlsearch_path_spec: libtool script contents. 5341 (line 334) 5342* sys_lib_search_path_spec: libtool script contents. 5343 (line 339) 5344* test suite: Libtool test suite. (line 6) 5345* test_compile: Porting inter-library dependencies. 5346 (line 26) 5347* tests, failed: When tests fail. (line 6) 5348* thread_safe_flag_spec: libtool script contents. 5349 (line 348) 5350* time, saving: Static-only libraries. 5351 (line 6) 5352* tricky design issues: Issues. (line 6) 5353* trouble with C++: C++ libraries. (line 6) 5354* trouble with dlopen: Dlopen issues. (line 6) 5355* troubleshooting: Troubleshooting. (line 6) 5356* undefined symbols, allowing: Link mode. (line 14) 5357* uninstall mode: Uninstall mode. (line 6) 5358* unknown: Porting inter-library dependencies. 5359 (line 43) 5360* unresolved symbols, allowing: Link mode. (line 14) 5361* using shared libraries, not: Static-only libraries. 5362 (line 6) 5363* version_type: libtool script contents. 5364 (line 352) 5365* versioning, formal: Libtool versioning. (line 6) 5366* whole_archive_flag_spec: libtool script contents. 5367 (line 357) 5368* wl: libtool script contents. 5369 (line 360) 5370* wrapper scripts for programs: Linking executables. (line 75) 5371 5372 5373 5374Tag Table: 5375Node: Top908 5376Node: Introduction6750 5377Node: Motivation8572 5378Node: Issues9892 5379Node: Other implementations11362 5380Node: Postmortem11905 5381Node: Libtool paradigm13526 5382Node: Using libtool14471 5383Node: Creating object files16585 5384Node: Linking libraries19099 5385Ref: Linking libraries-Footnote-122031 5386Node: Linking executables22172 5387Ref: Linking executables-Footnote-127181 5388Node: Debugging executables27474 5389Node: Installing libraries30182 5390Ref: Installing libraries-Footnote-133358 5391Node: Installing executables33440 5392Node: Static libraries34233 5393Node: Invoking libtool37492 5394Node: Compile mode40738 5395Node: Link mode43066 5396Node: Execute mode49881 5397Node: Install mode50661 5398Node: Finish mode52667 5399Node: Uninstall mode53102 5400Node: Clean mode53543 5401Node: Integrating libtool54002 5402Node: Makefile rules54685 5403Node: Using Automake55761 5404Node: Configuring58329 5405Node: AC_PROG_LIBTOOL59503 5406Ref: AC_PROG_LIBTOOL-Footnote-166835 5407Node: Distributing67096 5408Node: Invoking libtoolize68264 5409Node: Autoconf .o macros69999 5410Node: Static-only libraries71253 5411Ref: Static-only libraries-Footnote-172612 5412Node: Versioning72721 5413Node: Interfaces74093 5414Node: Libtool versioning74726 5415Node: Updating version info76939 5416Node: Release numbers78817 5417Node: Library tips80664 5418Node: C header files83473 5419Ref: C header files-Footnote-187144 5420Node: Inter-library dependencies87353 5421Node: Dlopened modules90015 5422Ref: Dlopened modules-Footnote-191928 5423Node: Building modules91994 5424Node: Dlpreopening93202 5425Node: Finding the dlname96036 5426Ref: Finding the dlname-Footnote-197335 5427Node: Dlopen issues97388 5428Node: Using libltdl98441 5429Node: Libltdl interface100221 5430Node: Modules for libltdl110376 5431Node: Thread Safety in libltdl112863 5432Node: User defined module data115076 5433Node: Module loaders for libltdl119899 5434Ref: Module loaders for libltdl-Footnote-1129290 5435Node: Distributing libltdl129396 5436Ref: Distributing libltdl-Footnote-1135914 5437Node: Other languages136139 5438Node: C++ libraries136771 5439Node: Troubleshooting138198 5440Node: Libtool test suite138733 5441Node: Test descriptions139466 5442Node: When tests fail145917 5443Node: Reporting bugs146812 5444Node: Maintaining148430 5445Node: New ports149173 5446Node: Information sources149866 5447Node: Porting inter-library dependencies152334 5448Node: Tested platforms155051 5449Node: Platform quirks163481 5450Node: References164455 5451Node: Compilers165312 5452Ref: Compilers-Footnote-1166888 5453Node: Reloadable objects167204 5454Node: Multiple dependencies167563 5455Node: Archivers168455 5456Node: libtool script contents169021 5457Node: Cheap tricks184257 5458Node: GNU Free Documentation License185760 5459Node: Index204459 5460 5461End Tag Table 5462