1This is ../doc/libtool.info, produced by makeinfo version 4.13 from 2../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* libtool-invocation: (libtool)Invoking libtool. 12 Running the `libtool' script. 13* libtoolize: (libtool)Invoking libtoolize. Adding libtool support. 14END-INFO-DIR-ENTRY 15 16 This file documents GNU Libtool 2.2.10 17 18 Copyright (C) 1996-2009 Free Software Foundation, Inc. 19 20 Permission is granted to copy, distribute and/or modify this document 21under the terms of the GNU Free Documentation License, Version 1.3 or 22any later version published by the Free Software Foundation; with no 23Invariant Sections, with no Front-Cover Texts, and with no Back-Cover 24Texts. A copy of the license is included in the section entitled "GNU 25Free Documentation License". 26 27 28File: libtool.info, Node: Top, Next: Introduction, Prev: (dir), Up: (dir) 29 30Shared library support for GNU 31****************************** 32 33This file documents GNU Libtool, a script that allows package developers 34to provide generic shared library support. This edition documents 35version 2.2.10. 36 37 *Note Reporting bugs::, for information on how to report problems 38with GNU Libtool. 39 40* Menu: 41 42* Introduction:: What the heck is libtool? 43* Libtool paradigm:: How libtool's view of libraries is different. 44* Using libtool:: Example of using libtool to build libraries. 45* Invoking libtool:: Running the `libtool' script. 46* Integrating libtool:: Using libtool in your own packages. 47* Other languages:: Using libtool without a C compiler. 48* Versioning:: Using library interface versions. 49* Library tips:: Tips for library interface design. 50* Inter-library dependencies:: Libraries that depend on other libraries. 51* Dlopened modules:: `dlopen'ing libtool-created libraries. 52* Using libltdl:: Libtool's portable `dlopen' wrapper library. 53* Trace interface:: Libtool's trace interface. 54* FAQ:: Frequently Asked Questions 55* Troubleshooting:: When libtool doesn't work as advertised. 56* Maintaining:: Information used by the libtool maintainer. 57* GNU Free Documentation License:: License for this manual. 58* Index:: Full index. 59 60 --- The Detailed Node Listing --- 61 62Introduction 63 64* Motivation:: Why does GNU need a libtool? 65* Issues:: The problems that need to be addressed. 66* Other implementations:: How other people have solved these issues. 67* Postmortem:: Learning from past difficulties. 68 69Using libtool 70 71* Creating object files:: Compiling object files for libraries. 72* Linking libraries:: Creating libraries from object files. 73* Linking executables:: Linking object files against libtool libraries. 74* Debugging executables:: Running GDB on libtool-generated programs. 75* Installing libraries:: Making libraries available to users. 76* Installing executables:: Making programs available to users. 77* Static libraries:: When shared libraries are not wanted. 78 79Linking executables 80 81* Wrapper executables:: Wrapper executables for some platforms. 82 83Invoking `libtool' 84 85* Compile mode:: Creating library object files. 86* Link mode:: Generating executables and libraries. 87* Execute mode:: Debugging libtool-generated programs. 88* Install mode:: Making libraries and executables public. 89* Finish mode:: Completing a library installation. 90* Uninstall mode:: Removing installed executables and libraries. 91* Clean mode:: Removing uninstalled executables and libraries. 92 93Integrating libtool with your package 94 95* Autoconf macros:: Autoconf macros exported by libtool. 96* Makefile rules:: Writing `Makefile' rules for libtool. 97* Using Automake:: Automatically supporting libtool. 98* Configuring:: Configuring libtool for a host system. 99* Distributing:: What files to distribute with your package. 100* Static-only libraries:: Sometimes shared libraries are just a pain. 101 102Configuring libtool 103 104* LT_INIT:: Configuring `libtool' in `configure.ac'. 105* Configure notes:: Platform-specific notes for configuration. 106 107Including libtool in your package 108 109* Invoking libtoolize:: `libtoolize' command line options. 110* Autoconf and LTLIBOBJS:: Autoconf automates LTLIBOBJS generation. 111 112Using libtool with other languages 113 114* C++ libraries:: Writing libraries for C++ 115* Tags:: Tags 116 117Library interface versions 118 119* Interfaces:: What are library interfaces? 120* Libtool versioning:: Libtool's versioning system. 121* Updating version info:: Changing version information before releases. 122* Release numbers:: Breaking binary compatibility for aesthetics. 123 124Tips for interface design 125 126* C header files:: How to write portable include files. 127 128Dlopened modules 129 130* Building modules:: Creating dlopenable objects and libraries. 131* Dlpreopening:: Dlopening that works on static platforms. 132* Linking with dlopened modules:: Using dlopenable modules in libraries. 133* Finding the dlname:: Choosing the right file to `dlopen'. 134* Dlopen issues:: Unresolved problems that need your attention. 135 136Using libltdl 137 138* Libltdl interface:: How to use libltdl in your programs. 139* Modules for libltdl:: Creating modules that can be `dlopen'ed. 140* Thread Safety in libltdl:: Registering callbacks for multi-thread safety. 141* User defined module data:: Associating data with loaded modules. 142* Module loaders for libltdl:: Creating user defined module loaders. 143* Distributing libltdl:: How to distribute libltdl with your package. 144 145Frequently Asked Questions 146 147* Stripped link flags:: Dropped flags when creating a library 148 149Troubleshooting 150 151* Libtool test suite:: Libtool's self-tests. 152* Reporting bugs:: How to report problems with libtool. 153 154The libtool test suite 155 156* Test descriptions:: The contents of the test suite. 157* When tests fail:: What to do when a test fails. 158 159Maintenance notes for libtool 160 161* New ports:: How to port libtool to new systems. 162* Tested platforms:: When libtool was last tested. 163* Platform quirks:: Information about different library systems. 164* libtool script contents:: Configuration information that libtool uses. 165* Cheap tricks:: Making libtool maintainership easier. 166 167Porting libtool to new systems 168 169* Information sources:: Where to find relevant documentation 170* Porting inter-library dependencies:: Implementation details explained 171 172Platform quirks 173 174* References:: Finding more information. 175* Compilers:: Creating object files from source files. 176* Reloadable objects:: Binding object files together. 177* Multiple dependencies:: Removing duplicate dependent libraries. 178* Archivers:: Programs that create static archives. 179 180 181File: libtool.info, Node: Introduction, Next: Libtool paradigm, Prev: Top, Up: Top 182 1831 Introduction 184************** 185 186In the past, if you were a source code package developer and wanted to 187take advantage of the power of shared libraries, you needed to write 188custom support code for each platform on which your package ran. You 189also had to design a configuration interface so that the package 190installer could choose what sort of libraries were built. 191 192 GNU Libtool simplifies your job by encapsulating both the 193platform-specific dependencies, and the user interface, in a single 194script. GNU Libtool is designed so that the complete functionality of 195each host type is available via a generic interface, but nasty quirks 196are hidden from the programmer. 197 198 GNU Libtool's consistent interface is reassuring... users don't need 199to read obscure documentation in order to have their favorite source 200package build shared libraries. They just run your package `configure' 201script (or equivalent), and libtool does all the dirty work. 202 203 There are several examples throughout this document. All assume the 204same environment: we want to build a library, `libhello', in a generic 205way. 206 207 `libhello' could be a shared library, a static library, or both... 208whatever is available on the host system, as long as libtool has been 209ported to it. 210 211 This chapter explains the original design philosophy of libtool. 212Feel free to skip to the next chapter, unless you are interested in 213history, or want to write code to extend libtool in a consistent way. 214 215* Menu: 216 217* Motivation:: Why does GNU need a libtool? 218* Issues:: The problems that need to be addressed. 219* Other implementations:: How other people have solved these issues. 220* Postmortem:: Learning from past difficulties. 221 222 223File: libtool.info, Node: Motivation, Next: Issues, Up: Introduction 224 2251.1 Motivation for writing libtool 226================================== 227 228Since early 1995, several different GNU developers have recognized the 229importance of having shared library support for their packages. The 230primary motivation for such a change is to encourage modularity and 231reuse of code (both conceptually and physically) in GNU programs. 232 233 Such a demand means that the way libraries are built in GNU packages 234needs to be general, to allow for any library type the package installer 235might want. The problem is compounded by the absence of a standard 236procedure for creating shared libraries on different platforms. 237 238 The following sections outline the major issues facing shared library 239support in GNU, and how shared library support could be standardized 240with libtool. 241 242 The following specifications were used in developing and evaluating 243this system: 244 245 1. The system must be as elegant as possible. 246 247 2. The system must be fully integrated with the GNU Autoconf and 248 Automake utilities, so that it will be easy for GNU maintainers to 249 use. However, the system must not require these tools, so that it 250 can be used by non-GNU packages. 251 252 3. Portability to other (non-GNU) architectures and tools is 253 desirable. 254 255 256File: libtool.info, Node: Issues, Next: Other implementations, Prev: Motivation, Up: Introduction 257 2581.2 Implementation issues 259========================= 260 261The following issues need to be addressed in any reusable shared library 262system, specifically libtool: 263 264 1. The package installer should be able to control what sort of 265 libraries are built. 266 267 2. It can be tricky to run dynamically linked programs whose 268 libraries have not yet been installed. `LD_LIBRARY_PATH' must be 269 set properly (if it is supported), or programs fail to run. 270 271 3. The system must operate consistently even on hosts that don't 272 support shared libraries. 273 274 4. The commands required to build shared libraries may differ wildly 275 from host to host. These need to be determined at configure time 276 in a consistent way. 277 278 5. It is not always obvious with what prefix or suffix a shared 279 library should be installed. This makes it difficult for 280 `Makefile' rules, since they generally assume that file names are 281 the same from host to host. 282 283 6. The system needs a simple library version number abstraction, so 284 that shared libraries can be upgraded in place. The programmer 285 should be informed how to design the interfaces to the library to 286 maximize binary compatibility. 287 288 7. The install `Makefile' target should warn the package installer to 289 set the proper environment variables (`LD_LIBRARY_PATH' or 290 equivalent), or run `ldconfig'. 291 292 293File: libtool.info, Node: Other implementations, Next: Postmortem, Prev: Issues, Up: Introduction 294 2951.3 Other implementations 296========================= 297 298Even before libtool was developed, many free software packages built and 299installed their own shared libraries. At first, these packages were 300examined to avoid reinventing existing features. 301 302 Now it is clear that none of these packages have documented the 303details of shared library systems that libtool requires. So, other 304packages have been more or less abandoned as influences. 305 306 307File: libtool.info, Node: Postmortem, Prev: Other implementations, Up: Introduction 308 3091.4 A postmortem analysis of other implementations 310================================================== 311 312In all fairness, each of the implementations that were examined do the 313job that they were intended to do, for a number of different host 314systems. However, none of these solutions seem to function well as a 315generalized, reusable component. 316 317 Most were too complex to use (much less modify) without understanding 318exactly what the implementation does, and they were generally not 319documented. 320 321 The main difficulty is that different vendors have different views of 322what libraries are, and none of the packages that were examined seemed 323to be confident enough to settle on a single paradigm that just _works_. 324 325 Ideally, libtool would be a standard that would be implemented as 326series of extensions and modifications to existing library systems to 327make them work consistently. However, it is not an easy task to 328convince operating system developers to mend their evil ways, and 329people want to build shared libraries right now, even on buggy, broken, 330confused operating systems. 331 332 For this reason, libtool was designed as an independent shell script. 333It isolates the problems and inconsistencies in library building that 334plague `Makefile' writers by wrapping the compiler suite on different 335platforms with a consistent, powerful interface. 336 337 With luck, libtool will be useful to and used by the GNU community, 338and that the lessons that were learned in writing it will be taken up by 339designers of future library systems. 340 341 342File: libtool.info, Node: Libtool paradigm, Next: Using libtool, Prev: Introduction, Up: Top 343 3442 The libtool paradigm 345********************** 346 347At first, libtool was designed to support an arbitrary number of library 348object types. After libtool was ported to more platforms, a new 349paradigm gradually developed for describing the relationship between 350libraries and programs. 351 352 In summary, "libraries are programs with multiple entry points, and 353more formally defined interfaces." 354 355 Version 0.7 of libtool was a complete redesign and rewrite of 356libtool to reflect this new paradigm. So far, it has proved to be 357successful: libtool is simpler and more useful than before. 358 359 The best way to introduce the libtool paradigm is to contrast it with 360the paradigm of existing library systems, with examples from each. It 361is a new way of thinking, so it may take a little time to absorb, but 362when you understand it, the world becomes simpler. 363 364 365File: libtool.info, Node: Using libtool, Next: Invoking libtool, Prev: Libtool paradigm, Up: Top 366 3673 Using libtool 368*************** 369 370It makes little sense to talk about using libtool in your own packages 371until you have seen how it makes your life simpler. The examples in 372this chapter introduce the main features of libtool by comparing the 373standard library building procedure to libtool's operation on two 374different platforms: 375 376`a23' 377 An Ultrix 4.2 platform with only static libraries. 378 379`burger' 380 A NetBSD/i386 1.2 platform with shared libraries. 381 382 You can follow these examples on your own platform, using the 383preconfigured libtool script that was installed with libtool (*note 384Configuring::). 385 386 Source files for the following examples are taken from the `demo' 387subdirectory of the libtool distribution. Assume that we are building a 388library, `libhello', out of the files `foo.c' and `hello.c'. 389 390 Note that the `foo.c' source file uses the `cos' math library 391function, which is usually found in the standalone math library, and not 392the C library (*note Trigonometric Functions: (libc)Trig Functions.). 393So, we need to add `-lm' to the end of the link line whenever we link 394`foo.lo' into an executable or a library (*note Inter-library 395dependencies::). 396 397 The same rule applies whenever you use functions that don't appear in 398the standard C library... you need to add the appropriate `-lNAME' flag 399to the end of the link line when you link against those objects. 400 401 After we have built that library, we want to create a program by 402linking `main.o' against `libhello'. 403 404* Menu: 405 406* Creating object files:: Compiling object files for libraries. 407* Linking libraries:: Creating libraries from object files. 408* Linking executables:: Linking object files against libtool libraries. 409* Debugging executables:: Running GDB on libtool-generated programs. 410* Installing libraries:: Making libraries available to users. 411* Installing executables:: Making programs available to users. 412* Static libraries:: When shared libraries are not wanted. 413 414 415File: libtool.info, Node: Creating object files, Next: Linking libraries, Up: Using libtool 416 4173.1 Creating object files 418========================= 419 420To create an object file from a source file, the compiler is invoked 421with the `-c' flag (and any other desired flags): 422 423 burger$ gcc -g -O -c main.c 424 burger$ 425 426 The above compiler command produces an object file, usually named 427`main.o', from the source file `main.c'. 428 429 For most library systems, creating object files that become part of a 430static library is as simple as creating object files that are linked to 431form an executable: 432 433 burger$ gcc -g -O -c foo.c 434 burger$ gcc -g -O -c hello.c 435 burger$ 436 437 Shared libraries, however, may only be built from 438"position-independent code" (PIC). So, special flags must be passed to 439the compiler to tell it to generate PIC rather than the standard 440position-dependent code. 441 442 Since this is a library implementation detail, libtool hides the 443complexity of PIC compiler flags and uses separate library object files 444(the PIC one lives in the `.libs' subdirectory and the static one lives 445in the current directory). On systems without shared libraries, the 446PIC library object files are not created, whereas on systems where all 447code is PIC, such as AIX, the static ones are not created. 448 449 To create library object files for `foo.c' and `hello.c', simply 450invoke libtool with the standard compilation command as arguments 451(*note Compile mode::): 452 453 a23$ libtool --mode=compile gcc -g -O -c foo.c 454 gcc -g -O -c foo.c -o foo.o 455 a23$ libtool --mode=compile gcc -g -O -c hello.c 456 gcc -g -O -c hello.c -o hello.o 457 a23$ 458 459 Note that libtool silently creates an additional control file on each 460`compile' invocation. The `.lo' file is the libtool object, which 461Libtool uses to determine what object file may be built into a shared 462library. On `a23', only static libraries are supported so the library 463objects look like this: 464 465 # foo.lo - a libtool object file 466 # Generated by ltmain.sh (GNU libtool) 2.2.10 467 # 468 # Please DO NOT delete this file! 469 # It is necessary for linking the library. 470 471 # Name of the PIC object. 472 pic_object=none 473 474 # Name of the non-PIC object. 475 non_pic_object='foo.o' 476 477 On shared library systems, libtool automatically generates an 478additional PIC object by inserting the appropriate PIC generation flags 479into the compilation command: 480 481 burger$ libtool --mode=compile gcc -g -O -c foo.c 482 mkdir .libs 483 gcc -g -O -c foo.c -fPIC -DPIC -o .libs/foo.o 484 gcc -g -O -c foo.c -o foo.o >/dev/null 2>&1 485 burger$ 486 487 Note that Libtool automatically created `.libs' directory upon its 488first execution, where PIC library object files will be stored. 489 490 Since `burger' supports shared libraries, and requires PIC objects 491to build them, Libtool has compiled a PIC object this time, and made a 492note of it in the libtool object: 493 494 # foo.lo - a libtool object file 495 # Generated by ltmain.sh (GNU libtool) 2.2.10 496 # 497 # Please DO NOT delete this file! 498 # It is necessary for linking the library. 499 500 # Name of the PIC object. 501 pic_object='.libs/foo.o' 502 503 # Name of the non-PIC object. 504 non_pic_object='foo.o' 505 506 Notice that the second run of GCC has its output discarded. This is 507done so that compiler warnings aren't annoyingly duplicated. If you 508need to see both sets of warnings (you might have conditional code 509inside `#ifdef PIC' for example), you can turn off suppression with the 510`-no-suppress' option to libtool's compile mode: 511 512 burger$ libtool --mode=compile gcc -no-suppress -g -O -c hello.c 513 gcc -g -O -c hello.c -fPIC -DPIC -o .libs/hello.o 514 gcc -g -O -c hello.c -o hello.o 515 burger$ 516 517 518File: libtool.info, Node: Linking libraries, Next: Linking executables, Prev: Creating object files, Up: Using libtool 519 5203.2 Linking libraries 521===================== 522 523Without libtool, the programmer would invoke the `ar' command to create 524a static library: 525 526 burger$ ar cru libhello.a hello.o foo.o 527 burger$ 528 529 But of course, that would be too simple, so many systems require that 530you run the `ranlib' command on the resulting library (to give it 531better karma, or something): 532 533 burger$ ranlib libhello.a 534 burger$ 535 536 It seems more natural to use the C compiler for this task, given 537libtool's "libraries are programs" approach. So, on platforms without 538shared libraries, libtool simply acts as a wrapper for the system `ar' 539(and possibly `ranlib') commands. 540 541 Again, the libtool control file name (`.la' suffix) differs from the 542standard library name (`.a' suffix). The arguments to libtool are the 543same ones you would use to produce an executable named `libhello.la' 544with your compiler (*note Link mode::): 545 546 a23$ libtool --mode=link gcc -g -O -o libhello.la foo.o hello.o 547 *** Warning: Linking the shared library libhello.la against the non-libtool 548 *** objects foo.o hello.o is not portable! 549 ar cru .libs/libhello.a 550 ranlib .libs/libhello.a 551 creating libhello.la 552 (cd .libs && rm -f libhello.la && ln -s ../libhello.la libhello.la) 553 a23$ 554 555 Aha! Libtool caught a common error... trying to build a library 556from standard objects instead of special `.lo' object files. This 557doesn't matter so much for static libraries, but on shared library 558systems, it is of great importance. (Note that you may replace 559`libhello.la' with `libhello.a' in which case libtool won't issue the 560warning any more. But although this method works, this is not intended 561to be used because it makes you lose the benefits of using Libtool.) 562 563 So, let's try again, this time with the library object files. 564Remember also that we need to add `-lm' to the link command line because 565`foo.c' uses the `cos' math library function (*note Using libtool::). 566 567 Another complication in building shared libraries is that we need to 568specify the path to the directory in which they (eventually) will be 569installed (in this case, `/usr/local/lib')(1): 570 571 a23$ libtool --mode=link gcc -g -O -o libhello.la foo.lo hello.lo \ 572 -rpath /usr/local/lib -lm 573 ar cru .libs/libhello.a foo.o hello.o 574 ranlib .libs/libhello.a 575 creating libhello.la 576 (cd .libs && rm -f libhello.la && ln -s ../libhello.la libhello.la) 577 a23$ 578 579 Now, let's try the same trick on the shared library platform: 580 581 burger$ libtool --mode=link gcc -g -O -o libhello.la foo.lo hello.lo \ 582 -rpath /usr/local/lib -lm 583 rm -fr .libs/libhello.a .libs/libhello.la 584 ld -Bshareable -o .libs/libhello.so.0.0 .libs/foo.o .libs/hello.o -lm 585 ar cru .libs/libhello.a foo.o hello.o 586 ranlib .libs/libhello.a 587 creating libhello.la 588 (cd .libs && rm -f libhello.la && ln -s ../libhello.la libhello.la) 589 burger$ 590 591 Now that's significantly cooler... Libtool just ran an obscure `ld' 592command to create a shared library, as well as the static library. 593 594 Note how libtool creates extra files in the `.libs' subdirectory, 595rather than the current directory. This feature is to make it easier 596to clean up the build directory, and to help ensure that other programs 597fail horribly if you accidentally forget to use libtool when you should. 598 599 Again, you may want to have a look at the `.la' file in order to see 600what Libtool stores in it. In particular, you will see that Libtool 601uses this file to remember the destination directory for the library 602(the argument to `-rpath') as well as the dependency on the math 603library (`-lm'). 604 605 ---------- Footnotes ---------- 606 607 (1) If you don't specify an `rpath', then libtool builds a libtool 608convenience archive, not a shared library (*note Static libraries::). 609 610 611File: libtool.info, Node: Linking executables, Next: Debugging executables, Prev: Linking libraries, Up: Using libtool 612 6133.3 Linking executables 614======================= 615 616If you choose at this point to "install" the library (put it in a 617permanent location) before linking executables against it, then you 618don't need to use libtool to do the linking. Simply use the appropriate 619`-L' and `-l' flags to specify the library's location. 620 621 Some system linkers insist on encoding the full directory name of 622each shared library in the resulting executable. Libtool has to work 623around this misfeature by special magic to ensure that only permanent 624directory names are put into installed executables. 625 626 The importance of this bug must not be overlooked: it won't cause 627programs to crash in obvious ways. It creates a security hole, and 628possibly even worse, if you are modifying the library source code after 629you have installed the package, you will change the behaviour of the 630installed programs! 631 632 So, if you want to link programs against the library before you 633install it, you must use libtool to do the linking. 634 635 Here's the old way of linking against an uninstalled library: 636 637 burger$ gcc -g -O -o hell.old main.o libhello.a -lm 638 burger$ 639 640 Libtool's way is almost the same(1) (*note Link mode::): 641 642 a23$ libtool --mode=link gcc -g -O -o hell main.o libhello.la 643 gcc -g -O -o hell main.o ./.libs/libhello.a -lm 644 a23$ 645 646 That looks too simple to be true. All libtool did was transform 647`libhello.la' to `./.libs/libhello.a', but remember that `a23' has no 648shared libraries. Notice that Libtool also remembered that 649`libhello.la' depends on `-lm', so even though we didn't specify `-lm' 650on the libtool command line(2) Libtool has added it to the `gcc' link 651line for us. 652 653 On `burger' Libtool links against the uninstalled shared library: 654 655 burger$ libtool --mode=link gcc -g -O -o hell main.o libhello.la 656 gcc -g -O -o .libs/hell main.o -L./.libs -R/usr/local/lib -lhello -lm 657 creating hell 658 burger$ 659 660 Now assume `libhello.la' had already been installed, and you want to 661link a new program with it. You could figure out where it lives by 662yourself, then run: 663 664 burger$ gcc -g -O -o test test.o -L/usr/local/lib -lhello -lm 665 666 However, unless `/usr/local/lib' is in the standard library search 667path, you won't be able to run `test'. However, if you use libtool to 668link the already-installed libtool library, it will do The Right Thing 669(TM) for you: 670 671 burger$ libtool --mode=link gcc -g -O -o test test.o \ 672 /usr/local/lib/libhello.la 673 gcc -g -O -o .libs/test test.o -Wl,--rpath \ 674 -Wl,/usr/local/lib /usr/local/lib/libhello.a -lm 675 creating test 676 burger$ 677 678 Note that libtool added the necessary run-time path flag, as well as 679`-lm', the library libhello.la depended upon. Nice, huh? 680 681 Notice that the executable, `hell', was actually created in the 682`.libs' subdirectory. Then, a wrapper script (or, on certain 683platforms, a wrapper executable *note Wrapper executables::) was 684created in the current directory. 685 686 Since libtool created a wrapper script, you should use libtool to 687install it and debug it too. However, since the program does not depend 688on any uninstalled libtool library, it is probably usable even without 689the wrapper script. 690 691 On NetBSD 1.2, libtool encodes the installation directory of 692`libhello', by using the `-R/usr/local/lib' compiler flag. Then, the 693wrapper script guarantees that the executable finds the correct shared 694library (the one in `./.libs') until it is properly installed. 695 696 Let's compare the two different programs: 697 698 burger$ time ./hell.old 699 Welcome to GNU Hell! 700 ** This is not GNU Hello. There is no built-in mail reader. ** 701 0.21 real 0.02 user 0.08 sys 702 burger$ time ./hell 703 Welcome to GNU Hell! 704 ** This is not GNU Hello. There is no built-in mail reader. ** 705 0.63 real 0.09 user 0.59 sys 706 burger$ 707 708 The wrapper script takes significantly longer to execute, but at 709least the results are correct, even though the shared library hasn't 710been installed yet. 711 712 So, what about all the space savings that shared libraries are 713supposed to yield? 714 715 burger$ ls -l hell.old libhello.a 716 -rwxr-xr-x 1 gord gord 15481 Nov 14 12:11 hell.old 717 -rw-r--r-- 1 gord gord 4274 Nov 13 18:02 libhello.a 718 burger$ ls -l .libs/hell .libs/libhello.* 719 -rwxr-xr-x 1 gord gord 11647 Nov 14 12:10 .libs/hell 720 -rw-r--r-- 1 gord gord 4274 Nov 13 18:44 .libs/libhello.a 721 -rwxr-xr-x 1 gord gord 12205 Nov 13 18:44 .libs/libhello.so.0.0 722 burger$ 723 724 Well, that sucks. Maybe I should just scrap this project and take up 725basket weaving. 726 727 Actually, it just proves an important point: shared libraries incur 728overhead because of their (relative) complexity. In this situation, the 729price of being dynamic is eight kilobytes, and the payoff is about four 730kilobytes. So, having a shared `libhello' won't be an advantage until 731we link it against at least a few more programs. 732 733* Menu: 734 735* Wrapper executables:: Wrapper executables for some platforms. 736 737 ---------- Footnotes ---------- 738 739 (1) However, you should avoid using `-L' or `-l' flags to link 740against an uninstalled libtool library. Just specify the relative path 741to the `.la' file, such as `../intl/libintl.la'. This is a design 742decision to eliminate any ambiguity when linking against uninstalled 743shared libraries. 744 745 (2) And why should we? `main.o' doesn't directly depend on `-lm' 746after all. 747 748 749File: libtool.info, Node: Wrapper executables, Up: Linking executables 750 7513.3.1 Wrapper executables for uninstalled programs 752-------------------------------------------------- 753 754Some platforms, notably those hosted on Windows such as Cygwin and 755MinGW, use a wrapper executable rather than a wrapper script to ensure 756proper operation of uninstalled programs linked by libtool against 757uninstalled shared libraries. The wrapper executable thus performs the 758same function as the wrapper script used on other platforms, but allows 759to satisfy the `make' rules for the program, whose name ends in 760`$(EXEEXT)'. The actual program executable is created below .libs, and 761its name will end in `$(EXEEXT)' and may or may not contain an `lt-' 762prefix. This wrapper executable sets various environment values so 763that the program executable may locate its (uninstalled) shared 764libraries, and then launches the program executable. 765 766 The wrapper executable provides a debug mode, enabled by passing the 767command-line option `--lt-debug' (see below). When executing in debug 768mode, diagnostic information will be printed to `stderr' before the 769program executable is launched. 770 771 Finally, the wrapper executable supports a number of command line 772options that may be useful when debugging the operation of the wrapper 773system. All of these options begin with `--lt-', and if present they 774and their arguments will be removed from the argument list passed on to 775the program executable. Therefore, the program executable may not 776employ command line options that begin with `--lt-'. (In fact, the 777wrapper executable will detect any command line options that begin with 778`--lt-' and abort with an error message if the option is not 779recognized). If this presents a problem, please contact the Libtool 780team at the Libtool bug reporting address <bug-libtool@gnu.org>. 781 782 These command line options include: 783 784`--lt-dump-script' 785 Causes the wrapper to print a copy of the wrapper _script_ to 786 `stdout', and exit. 787 788`--lt-debug' 789 Causes the wrapper to print diagnostic information to `stdout', 790 before launching the program executable. 791 792 793 For consistency, both the wrapper _script_ and the wrapper 794_executable_ support these options. 795 796 797File: libtool.info, Node: Debugging executables, Next: Installing libraries, Prev: Linking executables, Up: Using libtool 798 7993.4 Debugging executables 800========================= 801 802If `hell' was a complicated program, you would certainly want to test 803and debug it before installing it on your system. In the above 804section, you saw how the libtool wrapper script makes it possible to run 805the program directly, but unfortunately, this mechanism interferes with 806the debugger: 807 808 burger$ gdb hell 809 GDB is free software and you are welcome to distribute copies of it 810 under certain conditions; type "show copying" to see the conditions. 811 There is no warranty for GDB; type "show warranty" for details. 812 GDB 4.16 (i386-unknown-netbsd), (C) 1996 Free Software Foundation, Inc. 813 814 "hell": not in executable format: File format not recognized 815 816 (gdb) quit 817 burger$ 818 819 Sad. It doesn't work because GDB doesn't know where the executable 820lives. So, let's try again, by invoking GDB directly on the executable: 821 822 burger$ gdb .libs/hell 823 GNU gdb 5.3 (i386-unknown-netbsd) 824 Copyright 2002 Free Software Foundation, Inc. 825 GDB is free software, covered by the GNU General Public License, 826 and you are welcome to change it and/or distribute copies of it 827 under certain conditions. Type "show copying" to see the conditions. 828 There is no warranty for GDB. Type "show warranty" for details. 829 (gdb) break main 830 Breakpoint 1 at 0x8048547: file main.c, line 29. 831 (gdb) run 832 Starting program: /home/src/libtool/demo/.libs/hell 833 /home/src/libtool/demo/.libs/hell: can't load library 'libhello.so.0' 834 835 Program exited with code 020. 836 (gdb) quit 837 burger$ 838 839 Argh. Now GDB complains because it cannot find the shared library 840that `hell' is linked against. So, we must use libtool in order to 841properly set the library path and run the debugger. Fortunately, we can 842forget all about the `.libs' directory, and just run it on the 843executable wrapper (*note Execute mode::): 844 845 burger$ libtool --mode=execute gdb hell 846 GNU gdb 5.3 (i386-unknown-netbsd) 847 Copyright 2002 Free Software Foundation, Inc. 848 GDB is free software, covered by the GNU General Public License, 849 and you are welcome to change it and/or distribute copies of it 850 under certain conditions. Type "show copying" to see the conditions. 851 There is no warranty for GDB. Type "show warranty" for details. 852 (gdb) break main 853 Breakpoint 1 at 0x8048547: file main.c, line 29. 854 (gdb) run 855 Starting program: /home/src/libtool/demo/.libs/hell 856 857 Breakpoint 1, main (argc=1, argv=0xbffffc40) at main.c:29 858 29 printf ("Welcome to GNU Hell!\n"); 859 (gdb) quit 860 The program is running. Quit anyway (and kill it)? (y or n) y 861 burger$ 862 863 864File: libtool.info, Node: Installing libraries, Next: Installing executables, Prev: Debugging executables, Up: Using libtool 865 8663.5 Installing libraries 867======================== 868 869Installing libraries on a non-libtool system is quite 870straightforward... just copy them into place:(1) 871 872 burger$ su 873 Password: ******** 874 burger# cp libhello.a /usr/local/lib/libhello.a 875 burger# 876 877 Oops, don't forget the `ranlib' command: 878 879 burger# ranlib /usr/local/lib/libhello.a 880 burger# 881 882 Libtool installation is quite simple, as well. Just use the 883`install' or `cp' command that you normally would (*note Install 884mode::): 885 886 a23# libtool --mode=install cp libhello.la /usr/local/lib/libhello.la 887 cp libhello.la /usr/local/lib/libhello.la 888 cp .libs/libhello.a /usr/local/lib/libhello.a 889 ranlib /usr/local/lib/libhello.a 890 a23# 891 892 Note that the libtool library `libhello.la' is also installed, to 893help libtool with uninstallation (*note Uninstall mode::) and linking 894(*note Linking executables::) and to help programs with dlopening 895(*note Dlopened modules::). 896 897 Here is the shared library example: 898 899 burger# libtool --mode=install install -c libhello.la \ 900 /usr/local/lib/libhello.la 901 install -c .libs/libhello.so.0.0 /usr/local/lib/libhello.so.0.0 902 install -c libhello.la /usr/local/lib/libhello.la 903 install -c .libs/libhello.a /usr/local/lib/libhello.a 904 ranlib /usr/local/lib/libhello.a 905 burger# 906 907 It is safe to specify the `-s' (strip symbols) flag if you use a 908BSD-compatible install program when installing libraries. Libtool will 909either ignore the `-s' flag, or will run a program that will strip only 910debugging and compiler symbols from the library. 911 912 Once the libraries have been put in place, there may be some 913additional configuration that you need to do before using them. First, 914you must make sure that where the library is installed actually agrees 915with the `-rpath' flag you used to build it. 916 917 Then, running `libtool -n finish LIBDIR' can give you further hints 918on what to do (*note Finish mode::): 919 920 burger# libtool -n finish /usr/local/lib 921 PATH="$PATH:/sbin" ldconfig -m /usr/local/lib 922 ----------------------------------------------------------------- 923 Libraries have been installed in: 924 /usr/local/lib 925 926 To link against installed libraries in a given directory, LIBDIR, 927 you must use the `-LLIBDIR' flag during linking. 928 929 You will also need to do one of the following: 930 - add LIBDIR to the `LD_LIBRARY_PATH' environment variable 931 during execution 932 - add LIBDIR to the `LD_RUN_PATH' environment variable 933 during linking 934 - use the `-RLIBDIR' linker flag 935 936 See any operating system documentation about shared libraries for 937 more information, such as the ld and ld.so manual pages. 938 ----------------------------------------------------------------- 939 burger# 940 941 After you have completed these steps, you can go on to begin using 942the installed libraries. You may also install any executables that 943depend on libraries you created. 944 945 ---------- Footnotes ---------- 946 947 (1) Don't strip static libraries though, or they will be unusable. 948 949 950File: libtool.info, Node: Installing executables, Next: Static libraries, Prev: Installing libraries, Up: Using libtool 951 9523.6 Installing executables 953========================== 954 955If you used libtool to link any executables against uninstalled libtool 956libraries (*note Linking executables::), you need to use libtool to 957install the executables after the libraries have been installed (*note 958Installing libraries::). 959 960 So, for our Ultrix example, we would run: 961 962 a23# libtool --mode=install -c hell /usr/local/bin/hell 963 install -c hell /usr/local/bin/hell 964 a23# 965 966 On shared library systems that require wrapper scripts, libtool just 967ignores the wrapper script and installs the correct binary: 968 969 burger# libtool --mode=install -c hell /usr/local/bin/hell 970 install -c .libs/hell /usr/local/bin/hell 971 burger# 972 973 974File: libtool.info, Node: Static libraries, Prev: Installing executables, Up: Using libtool 975 9763.7 Linking static libraries 977============================ 978 979Why return to `ar' and `ranlib' silliness when you've had a taste of 980libtool? Well, sometimes it is desirable to create a static archive 981that can never be shared. The most frequent case is when you have a 982set of object files that you use to build several different libraries. 983You can create a "convenience library" out of those objects, and link 984against that with the other libraries, instead of listing all the 985object files every time. 986 987 If you just want to link this convenience library into programs, then 988you could just ignore libtool entirely, and use the old `ar' and 989`ranlib' commands (or the corresponding GNU Automake `_LIBRARIES' 990rules). You can even install a convenience library using GNU Libtool, 991though you probably don't want to and hence GNU Automake doesn't allow 992you to do so. 993 994 burger$ libtool --mode=install ./install-sh -c libhello.a \ 995 /local/lib/libhello.a 996 ./install-sh -c libhello.a /local/lib/libhello.a 997 ranlib /local/lib/libhello.a 998 burger$ 999 1000 Using libtool for static library installation protects your library 1001from being accidentally stripped (if the installer used the `-s' flag), 1002as well as automatically running the correct `ranlib' command. 1003 1004 But libtool libraries are more than just collections of object files: 1005they can also carry library dependency information, which old archives 1006do not. If you want to create a libtool static convenience library, you 1007can omit the `-rpath' flag and use `-static' to indicate that you're 1008only interested in a static library. When you link a program with such 1009a library, libtool will actually link all object files and dependency 1010libraries into the program. 1011 1012 If you omit both `-rpath' and `-static', libtool will create a 1013convenience library that can be used to create other libtool libraries, 1014even shared ones. Just like in the static case, the library behaves as 1015an alias to a set of object files and dependency libraries, but in this 1016case the object files are suitable for inclusion in shared libraries. 1017But be careful not to link a single convenience library, directly or 1018indirectly, into a single program or library, otherwise you may get 1019errors about symbol redefinitions. 1020 1021 The key is remembering that a convenience library contains PIC 1022objects, and can be linked where a list of PIC objects makes sense; 1023i.e. into a shared library. A static convenience library contains 1024non-PIC objects, so can be linked into an old static library, or a 1025program. 1026 1027 When GNU Automake is used, you should use `noinst_LTLIBRARIES' 1028instead of `lib_LTLIBRARIES' for convenience libraries, so that the 1029`-rpath' option is not passed when they are linked. 1030 1031 As a rule of thumb, link a libtool convenience library into at most 1032one libtool library, and never into a program, and link libtool static 1033convenience libraries only into programs, and only if you need to carry 1034library dependency information to the user of the static convenience 1035library. 1036 1037 Another common situation where static linking is desirable is in 1038creating a standalone binary. Use libtool to do the linking and add the 1039`-all-static' flag. 1040 1041 1042File: libtool.info, Node: Invoking libtool, Next: Integrating libtool, Prev: Using libtool, Up: Top 1043 10444 Invoking `libtool' 1045******************** 1046 1047The `libtool' program has the following synopsis: 1048 1049 libtool [OPTION]... [MODE-ARG]... 1050 1051and accepts the following options: 1052 1053`--config' 1054 Display libtool configuration variables and exit. 1055 1056`--debug' 1057 Dump a trace of shell script execution to standard output. This 1058 produces a lot of output, so you may wish to pipe it to `less' (or 1059 `more') or redirect to a file. 1060 1061`-n' 1062`--dry-run' 1063 Don't create, modify, or delete any files, just show what commands 1064 would be executed by libtool. 1065 1066`--features' 1067 Display basic configuration options. This provides a way for 1068 packages to determine whether shared or static libraries will be 1069 built. 1070 1071`--finish' 1072 Same as `--mode=finish'. 1073 1074`-h' 1075 Display short help message. 1076 1077`--help' 1078 Display a help message and exit. If `--mode=MODE' is specified, 1079 then detailed help for MODE is displayed. 1080 1081`--help-all' 1082 Display help for the general options as well as detailed help for 1083 each operation mode, and exit. 1084 1085`--mode=MODE' 1086 Use MODE as the operation mode. When using libtool from the 1087 command line, you can give just MODE (or a unique abbreviation of 1088 it) as the first argument as a shorthand for the full 1089 `--mode=MODE'. For example, the following are equivalent: 1090 1091 $ libtool --mode=execute --dry-run gdb prog.exe 1092 $ libtool execute --dry-run gdb prog.exe 1093 $ libtool exe --dry-run gdb prog.exe 1094 $ libtool e --dry-run gdb prog.exe 1095 1096 MODE must be set to one of the following: 1097 1098 `compile' 1099 Compile a source file into a libtool object. 1100 1101 `execute' 1102 Automatically set the library path so that another program 1103 can use uninstalled libtool-generated programs or libraries. 1104 1105 `link' 1106 Create a library or an executable. 1107 1108 `install' 1109 Install libraries or executables. 1110 1111 `finish' 1112 Complete the installation of libtool libraries on the system. 1113 1114 `uninstall' 1115 Delete installed libraries or executables. 1116 1117 `clean' 1118 Delete uninstalled libraries or executables. 1119 1120`--tag=TAG' 1121 Use configuration variables from tag TAG (*note Tags::). 1122 1123`--preserve-dup-deps' 1124 Do not remove duplicate dependencies in libraries. When building 1125 packages with static libraries, the libraries may depend 1126 circularly on each other (shared libs can too, but for those it 1127 doesn't matter), so there are situations, where -la -lb -la is 1128 required, and the second -la may not be stripped or the link will 1129 fail. In cases where these duplications are required, this option 1130 will preserve them, only stripping the libraries that libtool 1131 knows it can safely. 1132 1133`--quiet' 1134`--silent' 1135 Do not print out any progress or informational messages. 1136 1137`-v' 1138`--verbose' 1139 Print out progress and informational messages (enabled by default), 1140 as well as additional messages not ordinary seen by default. 1141 1142`--no-quiet' 1143`--no-silent' 1144 Print out the progress and informational messages that are seen by 1145 default. This option has no effect on whether the additional 1146 messages seen in `--verbose' mode are shown. 1147 1148`--no-verbose' 1149 Do not print out any additional informational messages beyond 1150 those ordinarily seen by default. This option has no effect on 1151 whether the ordinary progress and informational messages enabled 1152 by `--no-quiet' are shown. 1153 1154 Thus, there are now three different message levels (not counting 1155 `--debug'), depending on whether the normal messages and/or the 1156 additional verbose messages are displayed. Note that there is no 1157 mechanism to diplay verbose messages, without also displaying 1158 normal messages. 1159 1160 *default* 1161 Normal messages are displayed, verbose messages are not 1162 displayed. In addition to being the default mode, it can be 1163 forcibly achieved by using both option `--no-verbose' and 1164 either option `--no-silent' or option `--no-quiet'. 1165 1166 *silent* 1167 Neither normal messages nor verbose messages are displayed. 1168 This mode can be achieved using either option `--silent' or 1169 option `--quiet'. 1170 1171 *verbose* 1172 Both normal messages and verbose messages are displayed. This 1173 mode can be achieved using either option `-v' or option 1174 `--verbose'. 1175 1176`--version' 1177 Print libtool version information and exit. 1178 1179 The MODE-ARGS are a variable number of arguments, depending on the 1180selected operation mode. In general, each MODE-ARG is interpreted by 1181programs libtool invokes, rather than libtool itself. 1182 1183* Menu: 1184 1185* Compile mode:: Creating library object files. 1186* Link mode:: Generating executables and libraries. 1187* Execute mode:: Debugging libtool-generated programs. 1188* Install mode:: Making libraries and executables public. 1189* Finish mode:: Completing a library installation. 1190* Uninstall mode:: Removing installed executables and libraries. 1191* Clean mode:: Removing uninstalled executables and libraries. 1192 1193 1194File: libtool.info, Node: Compile mode, Next: Link mode, Up: Invoking libtool 1195 11964.1 Compile mode 1197================ 1198 1199For "compile" mode, MODE-ARGS is a compiler command to be used in 1200creating a "standard" object file. These arguments should begin with 1201the name of the C compiler, and contain the `-c' compiler flag so that 1202only an object file is created. 1203 1204 Libtool determines the name of the output file by removing the 1205directory component from the source file name, then substituting the 1206source code suffix (e.g. `.c' for C source code) with the library 1207object suffix, `.lo'. 1208 1209 If shared libraries are being built, any necessary PIC generation 1210flags are substituted into the compilation command. 1211 1212 The following components of MODE-ARGS are treated specially: 1213 1214`-o' 1215 Note that the `-o' option is now fully supported. It is emulated 1216 on the platforms that don't support it (by locking and moving the 1217 objects), so it is really easy to use libtool, just with minor 1218 modifications to your Makefiles. Typing for example 1219 libtool --mode=compile gcc -c foo/x.c -o foo/x.lo 1220 will do what you expect. 1221 1222 Note, however, that, if the compiler does not support `-c' and 1223 `-o', it is impossible to compile `foo/x.c' without overwriting an 1224 existing `./x.o'. Therefore, if you do have a source file 1225 `./x.c', make sure you introduce dependencies in your `Makefile' 1226 to make sure `./x.o' (or `./x.lo') is re-created after any 1227 sub-directory's `x.lo': 1228 1229 x.o x.lo: foo/x.lo bar/x.lo 1230 1231 This will also ensure that make won't try to use a temporarily 1232 corrupted `x.o' to create a program or library. It may cause 1233 needless recompilation on platforms that support `-c' and `-o' 1234 together, but it's the only way to make it safe for those that 1235 don't. 1236 1237`-no-suppress' 1238 If both PIC and non-PIC objects are being built, libtool will 1239 normally suppress the compiler output for the PIC object 1240 compilation to save showing very similar, if not identical 1241 duplicate output for each object. If the `-no-suppress' option is 1242 given in compile mode, libtool will show the compiler output for 1243 both objects. 1244 1245`-prefer-pic' 1246 Libtool will try to build only PIC objects. 1247 1248`-prefer-non-pic' 1249 Libtool will try to build only non-PIC objects. 1250 1251`-shared' 1252 Even if Libtool was configured with `--enable-static', the object 1253 file Libtool builds will not be suitable for static linking. 1254 Libtool will signal an error if it was configured with 1255 `--disable-shared', or if the host does not support shared 1256 libraries. 1257 1258`-static' 1259 Even if libtool was configured with `--disable-static', the object 1260 file Libtool builds *will* be suitable for static linking. 1261 1262`-Wc,FLAG' 1263`-Xcompiler FLAG' 1264 Pass a flag directly to the compiler. With `-Wc,', multiple flags 1265 may be separated by commas, whereas `-Xcompiler ' passes through 1266 commas unchanged. 1267 1268 1269File: libtool.info, Node: Link mode, Next: Execute mode, Prev: Compile mode, Up: Invoking libtool 1270 12714.2 Link mode 1272============= 1273 1274"Link" mode links together object files (including library objects) to 1275form another library or to create an executable program. 1276 1277 MODE-ARGS consist of a command using the C compiler to create an 1278output file (with the `-o' flag) from several object files. 1279 1280 The following components of MODE-ARGS are treated specially: 1281 1282`-all-static' 1283 If OUTPUT-FILE is a program, then do not link it against any 1284 shared libraries at all. If OUTPUT-FILE is a library, then only 1285 create a static library. In general, this flag cannot be used 1286 together with `disable-static' (*note LT_INIT::). 1287 1288`-avoid-version' 1289 Tries to avoid versioning (*note Versioning::) for libraries and 1290 modules, i.e. no version information is stored and no symbolic 1291 links are created. If the platform requires versioning, this 1292 option has no effect. 1293 1294`-bindir' 1295 Pass the absolute name of the directory for installing executable 1296 programs (*note Directory Variables: (standards)Directory 1297 Variables.). `libtool' may use this value to install shared 1298 libraries there on systems that do not provide for any library 1299 hardcoding and use the directory of a program and the `PATH' 1300 variable as library search path. This is typically used for DLLs 1301 on Windows or other systems using the PE (Portable Executable) 1302 format. On other systems, `-bindir' is ignored. The default 1303 value used is `LIBDIR/../bin' for libraries installed to `LIBDIR'. 1304 You should not use `-bindir' for modules. 1305 1306`-dlopen FILE' 1307 Same as `-dlpreopen FILE', if native dlopening is not supported on 1308 the host platform (*note Dlopened modules::) or if the program is 1309 linked with `-static', `-static-libtool-libs', or `-all-static'. 1310 Otherwise, no effect. If FILE is `self' Libtool will make sure 1311 that the program can `dlopen' itself, either by enabling 1312 `-export-dynamic' or by falling back to `-dlpreopen self'. 1313 1314`-dlpreopen FILE' 1315 Link FILE into the output program, and add its symbols to the list 1316 of preloaded symbols (*note Dlpreopening::). If FILE is `self', 1317 the symbols of the program itself will be added to preloaded 1318 symbol lists. If FILE is `force' Libtool will make sure that a 1319 preloaded symbol list is always _defined_, regardless of whether 1320 it's empty or not. 1321 1322`-export-dynamic' 1323 Allow symbols from OUTPUT-FILE to be resolved with `dlsym' (*note 1324 Dlopened modules::). 1325 1326`-export-symbols SYMFILE' 1327 Tells the linker to export only the symbols listed in SYMFILE. 1328 The symbol file should end in `.sym' and must contain the name of 1329 one symbol per line. This option has no effect on some platforms. 1330 By default all symbols are exported. 1331 1332`-export-symbols-regex REGEX' 1333 Same as `-export-symbols', except that only symbols matching the 1334 regular expression REGEX are exported. By default all symbols are 1335 exported. 1336 1337`-LLIBDIR' 1338 Search LIBDIR for required libraries that have already been 1339 installed. 1340 1341`-lNAME' 1342 OUTPUT-FILE requires the installed library `libNAME'. This option 1343 is required even when OUTPUT-FILE is not an executable. 1344 1345`-module' 1346 Creates a library that can be dlopened (*note Dlopened modules::). 1347 This option doesn't work for programs. Module names don't need to 1348 be prefixed with `lib'. In order to prevent name clashes, 1349 however, `libNAME' and `NAME' must not be used at the same time in 1350 your package. 1351 1352`-no-fast-install' 1353 Disable fast-install mode for the executable OUTPUT-FILE. Useful 1354 if the program won't be necessarily installed. 1355 1356`-no-install' 1357 Link an executable OUTPUT-FILE that can't be installed and 1358 therefore doesn't need a wrapper script on systems that allow 1359 hardcoding of library paths. Useful if the program is only used 1360 in the build tree, e.g., for testing or generating other files. 1361 1362`-no-undefined' 1363 Declare that OUTPUT-FILE does not depend on any other libraries. 1364 Some platforms cannot create shared libraries that depend on other 1365 libraries (*note Inter-library dependencies::). 1366 1367`-o OUTPUT-FILE' 1368 Create OUTPUT-FILE from the specified objects and libraries. 1369 1370`-objectlist FILE' 1371 Use a list of object files found in FILE to specify objects. 1372 1373`-precious-files-regex REGEX' 1374 Prevents removal of files from the temporary output directory whose 1375 names match this regular expression. You might specify `\.bbg?$' 1376 to keep those files created with `gcc -ftest-coverage' for example. 1377 1378`-release RELEASE' 1379 Specify that the library was generated by release RELEASE of your 1380 package, so that users can easily tell which versions are newer 1381 than others. Be warned that no two releases of your package will 1382 be binary compatible if you use this flag. If you want binary 1383 compatibility, use the `-version-info' flag instead (*note 1384 Versioning::). 1385 1386`-rpath LIBDIR' 1387 If OUTPUT-FILE is a library, it will eventually be installed in 1388 LIBDIR. If OUTPUT-FILE is a program, add LIBDIR to the run-time 1389 path of the program. On platforms that don't support hardcoding 1390 library paths into executables and only search PATH for shared 1391 libraries, such as when OUTPUT-FILE is a Windows (or other PE 1392 platform) DLL, the `.la' control file will be installed in LIBDIR, 1393 but see `-bindir' above for the eventual destination of the `.dll' 1394 or other library file itself. 1395 1396`-R LIBDIR' 1397 If OUTPUT-FILE is a program, add LIBDIR to its run-time path. If 1398 OUTPUT-FILE is a library, add `-RLIBDIR' to its DEPENDENCY_LIBS, 1399 so that, whenever the library is linked into a program, LIBDIR 1400 will be added to its run-time path. 1401 1402`-shared' 1403 If OUTPUT-FILE is a program, then link it against any uninstalled 1404 shared libtool libraries (this is the default behavior). If 1405 OUTPUT-FILE is a library, then only create a shared library. In 1406 the later case, libtool will signal an error if it was configured 1407 with `--disable-shared', or if the host does not support shared 1408 libraries. 1409 1410`-shrext SUFFIX' 1411 If OUTPUT-FILE is a libtool library, replace the system's standard 1412 file name extension for shared libraries with SUFFIX (most systems 1413 use `.so' here). This option is helpful in certain cases where an 1414 application requires that shared libraries (typically modules) 1415 have an extension other than the default one. Please note you 1416 must supply the full file name extension including any leading dot. 1417 1418`-static' 1419 If OUTPUT-FILE is a program, then do not link it against any 1420 uninstalled shared libtool libraries. If OUTPUT-FILE is a 1421 library, then only create a static library. 1422 1423`-static-libtool-libs' 1424 If OUTPUT-FILE is a program, then do not link it against any 1425 shared libtool libraries. If OUTPUT-FILE is a library, then only 1426 create a static library. 1427 1428`-version-info CURRENT[:REVISION[:AGE]]' 1429 If OUTPUT-FILE is a libtool library, use interface version 1430 information CURRENT, REVISION, and AGE to build it (*note 1431 Versioning::). Do *not* use this flag to specify package release 1432 information, rather see the `-release' flag. 1433 1434`-version-number MAJOR[:MINOR[:REVISION]]' 1435 If OUTPUT-FILE is a libtool library, compute interface version 1436 information so that the resulting library uses the specified 1437 major, minor and revision numbers. This is designed to permit 1438 libtool to be used with existing projects where identical version 1439 numbers are already used across operating systems. New projects 1440 should use the `-version-info' flag instead. 1441 1442`-weak LIBNAME' 1443 if OUTPUT-FILE is a libtool library, declare that it provides a 1444 weak LIBNAME interface. This is a hint to libtool that there is 1445 no need to append LIBNAME to the list of dependency libraries of 1446 OUTPUT-FILE, because linking against OUTPUT-FILE already supplies 1447 the same interface (*note Linking with dlopened modules::). 1448 1449`-Wc,FLAG' 1450`-Xcompiler FLAG' 1451 Pass a linker-specific flag directly to the compiler. With `-Wc,', 1452 multiple flags may be separated by commas, whereas `-Xcompiler ' 1453 passes through commas unchanged. 1454 1455`-Wl,FLAG' 1456`-Xlinker FLAG' 1457 Pass a linker-specific flag directly to the linker. 1458 1459`-XCClinker FLAG' 1460 Pass a link-specific flag to the compiler driver (CC) during 1461 linking. 1462 1463 If the OUTPUT-FILE ends in `.la', then a libtool library is created, 1464which must be built only from library objects (`.lo' files). The 1465`-rpath' option is required. In the current implementation, libtool 1466libraries may not depend on other uninstalled libtool libraries (*note 1467Inter-library dependencies::). 1468 1469 If the OUTPUT-FILE ends in `.a', then a standard library is created 1470using `ar' and possibly `ranlib'. 1471 1472 If OUTPUT-FILE ends in `.o' or `.lo', then a reloadable object file 1473is created from the input files (generally using `ld -r'). This method 1474is often called "partial linking". 1475 1476 Otherwise, an executable program is created. 1477 1478 1479File: libtool.info, Node: Execute mode, Next: Install mode, Prev: Link mode, Up: Invoking libtool 1480 14814.3 Execute mode 1482================ 1483 1484For "execute" mode, the library path is automatically set, then a 1485program is executed. 1486 1487 The first of the MODE-ARGS is treated as a program name, with the 1488rest as arguments to that program. 1489 1490 The following components of MODE-ARGS are treated specially: 1491 1492`-dlopen FILE' 1493 Add the directory containing FILE to the library path. 1494 1495 This mode sets the library path environment variable according to any 1496`-dlopen' flags. 1497 1498 If any of the ARGS are libtool executable wrappers, then they are 1499translated into the name of their corresponding uninstalled binary, and 1500any of their required library directories are added to the library path. 1501 1502 1503File: libtool.info, Node: Install mode, Next: Finish mode, Prev: Execute mode, Up: Invoking libtool 1504 15054.4 Install mode 1506================ 1507 1508In "install" mode, libtool interprets most of the elements of MODE-ARGS 1509as an installation command beginning with `cp', or a BSD-compatible 1510`install' program. 1511 1512 The following components of MODE-ARGS are treated specially: 1513 1514`-inst-prefix-dir INST-PREFIX-DIR' 1515 When installing into a temporary staging area, rather than the 1516 final PREFIX, this argument is used to reflect the temporary path, 1517 in much the same way `automake' uses DESTDIR. For instance, if 1518 PREFIX is `/usr/local', but INST-PREFIX-DIR is `/tmp', then the 1519 object will be installed under `/tmp/usr/local/'. If the 1520 installed object is a libtool library, then the internal fields of 1521 that library will reflect only PREFIX, not INST-PREFIX-DIR: 1522 1523 # Directory that this library needs to be installed in: 1524 libdir='/usr/local/lib' 1525 1526 not 1527 1528 # Directory that this library needs to be installed in: 1529 libdir='/tmp/usr/local/lib' 1530 1531 `inst-prefix' is also used to insure that if the installed object 1532 must be relinked upon installation, that it is relinked against 1533 the libraries in INST-PREFIX-DIR/PREFIX, not PREFIX. 1534 1535 In truth, this option is not really intended for use when calling 1536 libtool directly; it is automatically used when `libtool 1537 --mode=install' calls `libtool --mode=relink'. Libtool does this 1538 by analyzing the destination path given in the original `libtool 1539 --mode=install' command and comparing it to the expected 1540 installation path established during `libtool --mode=link'. 1541 1542 Thus, end-users need change nothing, and `automake'-style `make 1543 install DESTDIR=/tmp' will Just Work(tm) most of the time. For 1544 systems where fast installation can not be turned on, relinking 1545 may be needed. In this case, a `DESTDIR' install will fail. 1546 1547 Currently it is not generally possible to install into a temporary 1548 staging area that contains needed third-party libraries which are 1549 not yet visible at their final location. 1550 1551 The rest of the MODE-ARGS are interpreted as arguments to the `cp' 1552or `install' command. 1553 1554 The command is run, and any necessary unprivileged post-installation 1555commands are also completed. 1556 1557 1558File: libtool.info, Node: Finish mode, Next: Uninstall mode, Prev: Install mode, Up: Invoking libtool 1559 15604.5 Finish mode 1561=============== 1562 1563"Finish" mode helps system administrators install libtool libraries so 1564that they can be located and linked into user programs. 1565 1566 Each MODE-ARG is interpreted as the name of a library directory. 1567Running this command may require superuser privileges, so the 1568`--dry-run' option may be useful. 1569 1570 1571File: libtool.info, Node: Uninstall mode, Next: Clean mode, Prev: Finish mode, Up: Invoking libtool 1572 15734.6 Uninstall mode 1574================== 1575 1576"Uninstall" mode deletes installed libraries, executables and objects. 1577 1578 The first MODE-ARG is the name of the program to use to delete files 1579(typically `/bin/rm'). 1580 1581 The remaining MODE-ARGS are either flags for the deletion program 1582(beginning with a `-'), or the names of files to delete. 1583 1584 1585File: libtool.info, Node: Clean mode, Prev: Uninstall mode, Up: Invoking libtool 1586 15874.7 Clean mode 1588============== 1589 1590"Clean" mode deletes uninstalled libraries, executables, objects and 1591libtool's temporary files associated with them. 1592 1593 The first MODE-ARG is the name of the program to use to delete files 1594(typically `/bin/rm'). 1595 1596 The remaining MODE-ARGS are either flags for the deletion program 1597(beginning with a `-'), or the names of files to delete. 1598 1599 1600File: libtool.info, Node: Integrating libtool, Next: Other languages, Prev: Invoking libtool, Up: Top 1601 16025 Integrating libtool with your package 1603*************************************** 1604 1605This chapter describes how to integrate libtool with your packages so 1606that your users can install hassle-free shared libraries. 1607 1608* Menu: 1609 1610* Autoconf macros:: Autoconf macros exported by libtool. 1611* Makefile rules:: Writing `Makefile' rules for libtool. 1612* Using Automake:: Automatically supporting libtool. 1613* Configuring:: Configuring libtool for a host system. 1614* Distributing:: What files to distribute with your package. 1615* Static-only libraries:: Sometimes shared libraries are just a pain. 1616 1617 1618File: libtool.info, Node: Autoconf macros, Next: Makefile rules, Up: Integrating libtool 1619 16205.1 Autoconf macros exported by libtool 1621======================================= 1622 1623Libtool uses a number of macros to interrogate the host system when it 1624is being built, and you can use some of them yourself too. Although 1625there are a great many other macros in the libtool installed m4 files, 1626these do not form part of the published interface, and are subject to 1627change between releases. 1628 1629Macros in the `LT_CMD_' namespace check for various shell commands: 1630 1631 -- Macro: LT_CMD_MAX_LEN 1632 Finds the longest command line that can be safely passed to 1633 `$SHELL' without being truncated, and store in the shell variable 1634 `$max_cmd_len'. It is only an approximate value, but command 1635 lines of this length or shorter are guaranteed not to be truncated. 1636 1637Macros in the `LT_FUNC_' namespace check characteristics of library 1638functions: 1639 1640 -- Macro: LT_FUNC_DLSYM_USCORE 1641 `AC_DEFINE' the preprocessor symbol `DLSYM_USCORE' if we have to 1642 add an underscore to symbol-names passed in to `dlsym'. 1643 1644Macros in the `LT_LIB_' namespace check characteristics of system 1645libraries: 1646 1647 -- Macro: LT_LIB_M 1648 Set `LIBM' to the math library or libraries required on this 1649 machine, if any. 1650 1651 -- Macro: LT_LIB_DLLOAD 1652 This is the macro used by `libltdl' to determine which dlloaders 1653 to use on this machine, if any. Several shell variables are set 1654 (and `AC_SUBST'ed) depending on the dlload interfaces are 1655 available on this machine. `LT_DLLOADERS' contains a list of 1656 libtool libraries that can be used, and if necessary also sets 1657 `LIBADD_DLOPEN' if additional system libraries are required by the 1658 `dlopen' loader, and `LIBADD_SHL_LOAD' if additional system 1659 libraries are required by the `shl_load' loader, respectively. 1660 Finally some symbols are set in `config.h' depending on the 1661 loaders that are found to work: `HAVE_LIBDL', `HAVE_SHL_LOAD', 1662 `HAVE_DYLD', `HAVE_DLD'. 1663 1664Macros in the `LT_PATH_' namespace search the system for the full path 1665to particular system commands: 1666 1667 -- Macro: LT_PATH_LD 1668 Add a `--with-gnu-ld' option to `configure'. Try to find the path 1669 to the linker used by `$CC', and whether it is the GNU linker. 1670 The result is stored in the shell variable `$LD', which is 1671 `AC_SUBST'ed. 1672 1673 -- Macro: LT_PATH_NM 1674 Try to find a BSD-compatible `nm' or a MS-compatible `dumpbin' 1675 command on this machine. The result is stored in the shell 1676 variable `$NM', which is `AC_SUBST'ed. 1677 1678Macros in the `LT_SYS_' namespace probe for system characteristics: 1679 1680 -- Macro: LT_SYS_DLOPEN_SELF 1681 Tests whether a program can dlopen itself, and then also whether 1682 the same program can still dlopen itself when statically linked. 1683 Results are stored in the shell variables `$enable_dlopen_self' and 1684 `enable_dlopen_self_static' respectively. 1685 1686 -- Macro: LT_SYS_DLOPEN_DEPLIBS 1687 Define the preprocessor symbol `LTDL_DLOPEN_DEPLIBS' if the OS 1688 needs help to load dependent libraries for `dlopen' (or 1689 equivalent). 1690 1691 -- Macro: LT_SYS_DLSEARCH_PATH 1692 Define the preprocessor symbol `LT_DLSEARCH_PATH' to the system 1693 default library search path. 1694 1695 -- Macro: LT_SYS_MODULE_EXT 1696 Define the preprocessor symbol `LT_MODULE_EXT' to the extension 1697 used for runtime loadable modules. If you use libltdl to open 1698 modules, then you can simply use the libtool library extension, 1699 `.la'. 1700 1701 -- Macro: LT_SYS_MODULE_PATH 1702 Define the preprocessor symbol `LT_MODULE_PATH_VAR' to the name of 1703 the shell environment variable that determines the run-time module 1704 search path. 1705 1706 -- Macro: LT_SYS_SYMBOL_USCORE 1707 Set the shell variable `sys_symbol_underscore' to `no' unless the 1708 compiler prefixes global symbols with an underscore. 1709 1710 1711File: libtool.info, Node: Makefile rules, Next: Using Automake, Prev: Autoconf macros, Up: Integrating libtool 1712 17135.2 Writing `Makefile' rules for libtool 1714======================================== 1715 1716Libtool is fully integrated with Automake (*note Introduction: 1717(automake)Top.), starting with Automake version 1.2. 1718 1719 If you want to use libtool in a regular `Makefile' (or 1720`Makefile.in'), you are on your own. If you're not using Automake, and 1721you don't know how to incorporate libtool into your package you need to 1722do one of the following: 1723 1724 1. Download the latest Automake distribution from your nearest GNU 1725 mirror, install it, and start using it. 1726 1727 2. Learn how to write `Makefile' rules by hand. They're sometimes 1728 complex, but if you're clever enough to write rules for compiling 1729 your old libraries, then you should be able to figure out new 1730 rules for libtool libraries (hint: examine the `Makefile.in' in 1731 the `tests/demo' subdirectory of the libtool distribution... note 1732 especially that it was automatically generated from the 1733 `Makefile.am' by Automake). 1734 1735 1736File: libtool.info, Node: Using Automake, Next: Configuring, Prev: Makefile rules, Up: Integrating libtool 1737 17385.3 Using Automake with libtool 1739=============================== 1740 1741Libtool library support is implemented under the `LTLIBRARIES' primary. 1742 1743 Here are some samples from the Automake `Makefile.am' in the libtool 1744distribution's `demo' subdirectory. 1745 1746 First, to link a program against a libtool library, just use the 1747`program_LDADD'(1) variable: 1748 1749 bin_PROGRAMS = hell hell_static 1750 1751 # Build hell from main.c and libhello.la 1752 hell_SOURCES = main.c 1753 hell_LDADD = libhello.la 1754 1755 # Create a statically linked version of hell. 1756 hell_static_SOURCES = main.c 1757 hell_static_LDADD = libhello.la 1758 hell_static_LDFLAGS = -static 1759 1760 You may use the `program_LDFLAGS' variable to stuff in any flags you 1761want to pass to libtool while linking `program' (such as `-static' to 1762avoid linking uninstalled shared libtool libraries). 1763 1764 Building a libtool library is almost as trivial... note the use of 1765`libhello_la_LDFLAGS' to pass the `-version-info' (*note Versioning::) 1766option to libtool: 1767 1768 # Build a libtool library, libhello.la for installation in libdir. 1769 lib_LTLIBRARIES = libhello.la 1770 libhello_la_SOURCES = hello.c foo.c 1771 libhello_la_LDFLAGS = -version-info 3:12:1 1772 1773 The `-rpath' option is passed automatically by Automake (except for 1774libraries listed as `noinst_LTLIBRARIES'), so you should not specify it. 1775 1776 *Note Building a Shared Library: (automake)A Shared Library, for 1777more information. 1778 1779 ---------- Footnotes ---------- 1780 1781 (1) Since GNU Automake 1.5, the flags `-dlopen' or `-dlpreopen' 1782(*note Link mode::) can be employed with the PROGRAM_LDADD variable. 1783Unfortunately, older releases didn't accept these flags, so if you are 1784stuck with an ancient Automake, we recommend quoting the flag itself, 1785and setting PROGRAM_DEPENDENCIES too: 1786 1787 program_LDADD = "-dlopen" libfoo.la 1788 program_DEPENDENCIES = libfoo.la 1789 1790 1791File: libtool.info, Node: Configuring, Next: Distributing, Prev: Using Automake, Up: Integrating libtool 1792 17935.4 Configuring libtool 1794======================= 1795 1796Libtool requires intimate knowledge of your compiler suite and operating 1797system in order to be able to create shared libraries and link against 1798them properly. When you install the libtool distribution, a 1799system-specific libtool script is installed into your binary directory. 1800 1801 However, when you distribute libtool with your own packages (*note 1802Distributing::), you do not always know the compiler suite and 1803operating system that are used to compile your package. 1804 1805 For this reason, libtool must be "configured" before it can be used. 1806This idea should be familiar to anybody who has used a GNU `configure' 1807script. `configure' runs a number of tests for system features, then 1808generates the `Makefile's (and possibly a `config.h' header file), 1809after which you can run `make' and build the package. 1810 1811 Libtool adds its own tests to your `configure' script in order to 1812generate a libtool script for the installer's host machine. 1813 1814* Menu: 1815 1816* LT_INIT:: Configuring `libtool' in `configure.ac'. 1817* Configure notes:: Platform-specific notes for configuration. 1818 1819 1820File: libtool.info, Node: LT_INIT, Next: Configure notes, Up: Configuring 1821 18225.4.1 The `LT_INIT' macro 1823------------------------- 1824 1825If you are using GNU Autoconf (or Automake), you should add a call to 1826`LT_INIT' to your `configure.ac' file. This macro adds many new tests 1827to the `configure' script so that the generated libtool script will 1828understand the characteristics of the host. It's the most important of 1829a number of macros defined by Libtool: 1830 1831 -- Macro: LT_PREREQ (VERSION) 1832 Ensure that a recent enough version of Libtool is being used. If 1833 the version of Libtool used for `LT_INIT' is earlier than VERSION, 1834 print an error message to the standard error output and exit with 1835 failure (exit status is 63). For example: 1836 1837 LT_PREREQ([2.2.10]) 1838 1839 -- Macro: LT_INIT (OPTIONS) 1840 -- Macro: AC_PROG_LIBTOOL 1841 -- Macro: AM_PROG_LIBTOOL 1842 Add support for the `--enable-shared' and `--disable-shared' 1843 `configure' flags.(1) `AC_PROG_LIBTOOL' and `AM_PROG_LIBTOOL' are 1844 deprecated names for older versions of this macro; `autoupdate' 1845 will upgrade your `configure.ac' files. 1846 1847 By default, this macro turns on shared libraries if they are 1848 available, and also enables static libraries if they don't 1849 conflict with the shared libraries. You can modify these defaults 1850 by passing either `disable-shared' or `disable-static' in the 1851 option list to `LT_INIT', or using `AC_DISABLE_SHARED' or 1852 `AC_DISABLE_STATIC'. 1853 1854 # Turn off shared libraries during beta-testing, since they 1855 # make the build process take too long. 1856 LT_INIT([disable-shared]) 1857 1858 The user may specify modified forms of the configure flags 1859 `--enable-shared' and `--enable-static' to choose whether shared 1860 or static libraries are built based on the name of the package. 1861 For example, to have shared `bfd' and `gdb' libraries built, but 1862 not shared `libg++', you can run all three `configure' scripts as 1863 follows: 1864 1865 trick$ ./configure --enable-shared=bfd,gdb 1866 1867 In general, specifying `--enable-shared=PKGS' is the same as 1868 configuring with `--enable-shared' every package named in the 1869 comma-separated PKGS list, and every other package with 1870 `--disable-shared'. The `--enable-static=PKGS' flag behaves 1871 similarly, but it uses `--enable-static' and `--disable-static'. 1872 The same applies to the `--enable-fast-install=PKGS' flag, which 1873 uses `--enable-fast-install' and `--disable-fast-install'. 1874 1875 The package name `default' matches any packages that have not set 1876 their name in the `PACKAGE' environment variable. 1877 1878 This macro also sets the shell variable LIBTOOL_DEPS, that you can 1879 use to automatically update the libtool script if it becomes 1880 out-of-date. In order to do that, add to your `configure.ac': 1881 1882 LT_INIT 1883 AC_SUBST([LIBTOOL_DEPS]) 1884 1885 and, to `Makefile.in' or `Makefile.am': 1886 1887 LIBTOOL_DEPS = @LIBTOOL_DEPS@ 1888 libtool: $(LIBTOOL_DEPS) 1889 $(SHELL) ./config.status libtool 1890 1891 If you are using GNU Automake, you can omit the assignment, as 1892 Automake will take care of it. You'll obviously have to create 1893 some dependency on `libtool'. 1894 1895 Aside from `disable-static' and `disable-shared', there are other 1896 options that you can pass to `LT_INIT' to modify its behaviour. 1897 Here is a full list: 1898 1899 `dlopen' 1900 Enable checking for dlopen support. This option should be 1901 used if the package makes use of the `-dlopen' and 1902 `-dlpreopen' libtool flags, otherwise libtool will assume 1903 that the system does not support dlopening. 1904 1905 `win32-dll' 1906 This option should be used if the package has been ported to 1907 build clean dlls on win32 platforms. Usually this means that 1908 any library data items are exported with 1909 `__declspec(dllexport)' and imported with 1910 `__declspec(dllimport)'. If this macro is not used, libtool 1911 will assume that the package libraries are not dll clean and 1912 will build only static libraries on win32 hosts. 1913 1914 Provision must be made to pass `-no-undefined' to `libtool' 1915 in link mode from the package `Makefile'. Naturally, if you 1916 pass `-no-undefined', you must ensure that all the library 1917 symbols *really are* defined at link time! 1918 1919 `disable-fast-install' 1920 Change the default behaviour for `LT_INIT' to disable 1921 optimization for fast installation. The user may still 1922 override this default, depending on platform support, by 1923 specifying `--enable-fast-install' to `configure'. 1924 1925 `shared' 1926 Change the default behaviour for `LT_INIT' to enable shared 1927 libraries. This is the default on all systems where Libtool 1928 knows how to create shared libraries. The user may still 1929 override this default by specifying `--disable-shared' to 1930 `configure'. 1931 1932 `disable-shared' 1933 Change the default behaviour for `LT_INIT' to disable shared 1934 libraries. The user may still override this default by 1935 specifying `--enable-shared' to `configure'. 1936 1937 `static' 1938 Change the default behaviour for `LT_INIT' to enable static 1939 libraries. This is the default on all systems where shared 1940 libraries have been disabled for some reason, and on most 1941 systems where shared libraries have been enabled. If shared 1942 libraries are enabled, the user may still override this 1943 default by specifying `--disable-static' to `configure'. 1944 1945 `disable-static' 1946 Change the default behaviour for `LT_INIT' to disable static 1947 libraries. The user may still override this default by 1948 specifying `--enable-static' to `configure'. 1949 1950 `pic-only' 1951 Change the default behaviour for `libtool' to try to use only 1952 PIC objects. The user may still override this default by 1953 specifying `--without-pic' to `configure'. 1954 1955 `no-pic' 1956 Change the default behaviour of `libtool' to try to use only 1957 non-PIC objects. The user may still override this default by 1958 specifying `--with-pic' to `configure'. 1959 1960 1961 1962 -- Macro: LT_LANG (LANGUAGE) 1963 Enable `libtool' support for the language given if it has not yet 1964 already been enabled. Languages accepted are "C++", "Fortran 77", 1965 "Java" and "Windows Resource". 1966 1967 If Autoconf language support macros such as `AC_PROG_CXX' are used 1968 in your `configure.ac', Libtool language support will automatically 1969 be enabled. 1970 1971 Conversely using `LT_LANG' to enable language support for Libtool 1972 will automatically enable Autoconf language support as well. 1973 1974 Both of the following examples are therefore valid ways of adding 1975 C++ language support to Libtool. 1976 1977 LT_INIT 1978 LT_LANG([C++]) 1979 1980 LT_INIT 1981 AC_PROG_CXX 1982 1983 1984 -- Macro: AC_LIBTOOL_DLOPEN 1985 This macro is deprecated, the `dlopen' option to `LT_INIT' should 1986 be used instead. 1987 1988 -- Macro: AC_LIBTOOL_WIN32_DLL 1989 This macro is deprecated, the `win32-dll' option to `LT_INIT' 1990 should be used instead. 1991 1992 -- Macro: AC_DISABLE_FAST_INSTALL 1993 This macro is deprecated, the `disable-fast-install' option to 1994 `LT_INIT' should be used instead. 1995 1996 -- Macro: AC_DISABLE_SHARED 1997 -- Macro: AM_DISABLE_SHARED 1998 Change the default behaviour for `LT_INIT' to disable shared 1999 libraries. The user may still override this default by specifying 2000 `--enable-shared'. The option `disable-shared' to `LT_INIT' is a 2001 shorthand for this. `AM_DISABLE_SHARED' is a deprecated alias for 2002 `AC_DISABLE_SHARED'. 2003 2004 -- Macro: AC_ENABLE_SHARED 2005 -- Macro: AM_ENABLE_SHARED 2006 Change the default behaviour for `LT_INIT' to enable shared 2007 libraries. This is the default on all systems where Libtool knows 2008 how to create shared libraries. The user may still override this 2009 default by specifying `--disable-shared'. The option `shared' to 2010 `LT_INIT' is a shorthand for this. `AM_ENABLE_SHARED' is a 2011 deprecated alias for `AC_ENABLE_SHARED'. 2012 2013 -- Macro: AC_DISABLE_STATIC 2014 -- Macro: AM_DISABLE_STATIC 2015 Change the default behaviour for `LT_INIT' to disable static 2016 libraries. The user may still override this default by specifying 2017 `--enable-static'. The option `disable-static' to `LT_INIT' is a 2018 shorthand for this. `AM_DISABLE_STATIC' is a deprecated alias for 2019 `AC_DISABLE_STATIC'. 2020 2021 -- Macro: AC_ENABLE_STATIC 2022 -- Macro: AM_ENABLE_STATIC 2023 Change the default behaviour for `LT_INIT' to enable static 2024 libraries. This is the default on all systems where shared 2025 libraries have been disabled for some reason, and on most systems 2026 where shared libraries have been enabled. If shared libraries are 2027 enabled, the user may still override this default by specifying 2028 `--disable-static'. The option `static' to `LT_INIT' is a 2029 shorthand for this. `AM_ENABLE_STATIC' is a deprecated alias for 2030 `AC_ENABLE_STATIC'. 2031 2032 The tests in `LT_INIT' also recognize the following environment 2033variables: 2034 2035 -- Variable: CC 2036 The C compiler that will be used by the generated `libtool'. If 2037 this is not set, `LT_INIT' will look for `gcc' or `cc'. 2038 2039 -- Variable: CFLAGS 2040 Compiler flags used to generate standard object files. If this is 2041 not set, `LT_INIT' will not use any such flags. It affects only 2042 the way `LT_INIT' runs tests, not the produced `libtool'. 2043 2044 -- Variable: CPPFLAGS 2045 C preprocessor flags. If this is not set, `LT_INIT' will not use 2046 any such flags. It affects only the way `LT_INIT' runs tests, not 2047 the produced `libtool'. 2048 2049 -- Variable: LD 2050 The system linker to use (if the generated `libtool' requires one). 2051 If this is not set, `LT_INIT' will try to find out what is the 2052 linker used by CC. 2053 2054 -- Variable: LDFLAGS 2055 The flags to be used by `libtool' when it links a program. If 2056 this is not set, `LT_INIT' will not use any such flags. It 2057 affects only the way `LT_INIT' runs tests, not the produced 2058 `libtool'. 2059 2060 -- Variable: LIBS 2061 The libraries to be used by `LT_INIT' when it links a program. If 2062 this is not set, `LT_INIT' will not use any such flags. It 2063 affects only the way `LT_INIT' runs tests, not the produced 2064 `libtool'. 2065 2066 -- Variable: NM 2067 Program to use rather than checking for `nm'. 2068 2069 -- Variable: RANLIB 2070 Program to use rather than checking for `ranlib'. 2071 2072 -- Variable: LN_S 2073 A command that creates a link of a program, a soft-link if 2074 possible, a hard-link otherwise. `LT_INIT' will check for a 2075 suitable program if this variable is not set. 2076 2077 -- Variable: DLLTOOL 2078 Program to use rather than checking for `dlltool'. Only meaningful 2079 for Cygwin/MS-Windows. 2080 2081 -- Variable: OBJDUMP 2082 Program to use rather than checking for `objdump'. Only meaningful 2083 for Cygwin/MS-Windows. 2084 2085 -- Variable: AS 2086 Program to use rather than checking for `as'. Only used on 2087 Cygwin/MS-Windows at the moment. 2088 2089 With 1.3 era libtool, if you wanted to know any details of what 2090libtool had discovered about your architecture and environment, you had 2091to run the script with `--config' and grep through the results. This 2092idiom was supported up to and including 1.5.x era libtool, where it was 2093possible to call the generated libtool script from `configure.ac' as 2094soon as `LT_INIT' had completed. However, one of the features of 2095libtool 1.4 was that the libtool configuration was migrated out of a 2096separate `ltconfig' file, and added to the `LT_INIT' macro (nee 2097`AC_PROG_LIBTOOL'), so the results of the configuration tests were 2098available directly to code in `configure.ac', rendering the call out to 2099the generated libtool script obsolete. 2100 2101 Starting with libtool 2.0, the multipass generation of the libtool 2102script has been consolidated into a single `config.status' pass, which 2103happens after all the code in `configure.ac' has completed. The 2104implication of this is that the libtool script does not exist during 2105execution of code from `configure.ac', and so obviously it cannot be 2106called for `--config' details anymore. If you are upgrading projects 2107that used this idiom to libtool 2.0 or newer, you should replace those 2108calls with direct references to the equivalent Autoconf shell variables 2109that are set by the configure time tests before being passed to 2110`config.status' for inclusion in the generated libtool script. 2111 2112 -- Macro: LT_OUTPUT 2113 By default, the configured `libtool' script is generated by the 2114 call to `AC_OUTPUT' command, and there is rarely any need to use 2115 `libtool' from `configure'. However, sometimes it is necessary to 2116 run configure time compile and link tests using `libtool'. You 2117 can add `LT_OUTPUT' to your `configure.ac' any time after 2118 `LT_INIT' and any `LT_LANG' calls; that done, `libtool' will be 2119 created by a specially generated `config.lt' file, and available 2120 for use in later tests. 2121 2122 Also, when `LT_OUTPUT' is used, for backwards compatibility with 2123 Automake regeneration rules, `config.status' will call `config.lt' 2124 to regenerate `libtool', rather than generating the file itself. 2125 2126 When you invoke the `libtoolize' program (*note Invoking 2127libtoolize::), it will tell you where to find a definition of 2128`LT_INIT'. If you use Automake, the `aclocal' program will 2129automatically add `LT_INIT' support to your `configure' script when it 2130sees the invocation of `LT_INIT' in `configure.ac'. 2131 2132 Because of these changes, and the runtime version compatibility 2133checks Libtool now executes, we now advise *against* including a copy of 2134`libtool.m4' (and brethren) in `acinclude.m4'. Instead, you should set 2135your project macro directory with `AC_CONFIG_MACRO_DIR'. When you 2136`libtoolize' your project, a copy of the relevant macro definitions 2137will be placed in your `AC_CONFIG_MACRO_DIR', where `aclocal' can 2138reference them directly from `aclocal.m4'. 2139 2140 ---------- Footnotes ---------- 2141 2142 (1) `LT_INIT' requires that you define the `Makefile' variable 2143`top_builddir' in your `Makefile.in'. Automake does this 2144automatically, but Autoconf users should set it to the relative path to 2145the top of your build directory (`../..', for example). 2146 2147 2148File: libtool.info, Node: Configure notes, Prev: LT_INIT, Up: Configuring 2149 21505.4.2 Platform-specific configuration notes 2151------------------------------------------- 2152 2153While Libtool tries to hide as many platform-specific features as 2154possible, some have to be taken into account when configuring either 2155the Libtool package or a libtoolized package. 2156 2157 * You currently need GNU make to build the Libtool package itself. 2158 2159 * On AIX there are two different styles of shared linking, one in 2160 which symbols are bound at link-time and one in which symbols are 2161 bound at runtime only, similar to ELF. In case of doubt use 2162 `LDFLAGS=-Wl,-brtl' for the latter style. 2163 2164 * On AIX, native tools are to be preferred over binutils; especially 2165 for C++ code, if using the AIX Toolbox GCC 4.0 and binutils, 2166 configure with `AR=/usr/bin/ar LD=/usr/bin/ld NM='/usr/bin/nm -B''. 2167 2168 * On AIX, the `/bin/sh' is very slow due to its inefficient handling 2169 of here-documents. A modern shell is preferable: 2170 CONFIG_SHELL=/bin/bash; export $CONFIG_SHELL 2171 $CONFIG_SHELL ./configure [...] 2172 2173 * For C++ code with templates, it may be necessary to specify the 2174 way the compiler will generate the instantiations. For Portland 2175 pgCC version5, use `CXX='pgCC --one_instantiation_per_object'' and 2176 avoid parallel `make'. 2177 2178 * On Darwin, for C++ code with templates you need two level shared 2179 libraries. Libtool builds these by default if 2180 `MACOSX_DEPLOYMENT_TARGET' is set to 10.3 or later at `configure' 2181 time. See `rdar://problem/4135857' for more information on this 2182 issue. 2183 2184 * The default shell on UNICOS 9, a ksh 88e variant, is too buggy to 2185 correctly execute the libtool script. Users are advised to 2186 install a modern shell such as GNU bash. 2187 2188 * Some HP-UX `sed' programs are horribly broken, and cannot handle 2189 libtool's requirements, so users may report unusual problems. 2190 There is no workaround except to install a working `sed' (such as 2191 GNU sed) on these systems. 2192 2193 * The vendor-distributed NCR MP-RAS `cc' programs emits copyright on 2194 standard error that confuse tests on size of `conftest.err'. The 2195 workaround is to specify `CC' when run configure with `CC='cc 2196 -Hnocopyr''. 2197 2198 * Any earlier DG/UX system with ELF executables, such as R3.10 or 2199 R4.10, is also likely to work, but hasn't been explicitly tested. 2200 2201 * On Reliant Unix libtool has only been tested with the Siemens 2202 C-compiler and an old version of `gcc' provided by Marco Walther. 2203 2204 * `libtool.m4', `ltdl.m4' and the `configure.ac' files are marked to 2205 use autoconf-mode, which is distributed with GNU Emacs 21, 2206 Autoconf itself, and all recent releases of XEmacs. 2207 2208 * When building on some linux systems for multilib targets `libtool' 2209 sometimes guesses the wrong paths that the linker and dynamic 2210 linker search by default. If this occurs, you may override 2211 libtool's guesses at `configure' time by setting the `autoconf' 2212 cache variables `lt_cv_sys_lib_search_path_spec' and 2213 `lt_cv_sys_lib_dlsearch_path_spec' respectively to the correct 2214 search paths. 2215 2216 2217 2218File: libtool.info, Node: Distributing, Next: Static-only libraries, Prev: Configuring, Up: Integrating libtool 2219 22205.5 Including libtool in your package 2221===================================== 2222 2223In order to use libtool, you need to include the following files with 2224your package: 2225 2226`config.guess' 2227 Attempt to guess a canonical system name. 2228 2229`config.sub' 2230 Canonical system name validation subroutine script. 2231 2232`install-sh' 2233 BSD-compatible `install' replacement script. 2234 2235`ltmain.sh' 2236 A generic script implementing basic libtool functionality. 2237 2238 Note that the libtool script itself should _not_ be included with 2239your package. *Note Configuring::. 2240 2241 You should use the `libtoolize' program, rather than manually 2242copying these files into your package. 2243 2244* Menu: 2245 2246* Invoking libtoolize:: `libtoolize' command line options. 2247* Autoconf and LTLIBOBJS:: Autoconf automates LTLIBOBJS generation. 2248 2249 2250File: libtool.info, Node: Invoking libtoolize, Next: Autoconf and LTLIBOBJS, Up: Distributing 2251 22525.5.1 Invoking `libtoolize' 2253--------------------------- 2254 2255The `libtoolize' program provides a standard way to add libtool support 2256to your package. In the future, it may implement better usage 2257checking, or other features to make libtool even easier to use. 2258 2259 The `libtoolize' program has the following synopsis: 2260 2261 libtoolize [OPTION]... 2262 2263and accepts the following options: 2264 2265`--copy' 2266`-c' 2267 Copy files from the libtool data directory rather than creating 2268 symlinks. 2269 2270`--debug' 2271 Dump a trace of shell script execution to standard output. This 2272 produces a lot of output, so you may wish to pipe it to `less' (or 2273 `more') or redirect to a file. 2274 2275`--dry-run' 2276`-n' 2277 Don't run any commands that modify the file system, just print them 2278 out. 2279 2280`--force' 2281`-f' 2282 Replace existing libtool files. By default, `libtoolize' won't 2283 overwrite existing files. 2284 2285`--help' 2286 Display a help message and exit. 2287 2288`--ltdl [TARGET-DIRECTORY-NAME]' 2289 Install libltdl in the TARGET-DIRECTORY-NAME subdirectory of your 2290 package. Normally, the directory is extracted from the argument 2291 to `LT_CONFIG_LTDL_DIR' in `configure.ac', though you can also 2292 specify a subdirectory name here if you are not using Autoconf for 2293 example. If `libtoolize' can't determine the target directory, 2294 `libltdl' is used as the default. 2295 2296`--no-warn' 2297 Normally, Libtoolize tries to diagnose use of deprecated libtool 2298 macros and other stylistic issues. If you are deliberately using 2299 outdated calling conventions, this option prevents Libtoolize from 2300 explaining how to update your project's Libtool conventions. 2301 2302`--nonrecursive' 2303 If passed in conjunction with `--ltdl', this option will cause the 2304 `libltdl' installed by `libtoolize' to be set up for use with a 2305 non-recursive `automake' build. To make use of it, you will need 2306 to add the following to the `Makefile.am' of the parent project: 2307 2308 ## libltdl/Makefile.inc appends to the following variables 2309 ## so we set them here before including it: 2310 BUILT_SOURCES = 2311 2312 AM_CPPFLAGS = 2313 AM_LDFLAGS = 2314 2315 include_HEADERS = 2316 noinst_LTLIBRARIES = 2317 lib_LTLIBRARIES = 2318 EXTRA_LTLIBRARIES = 2319 2320 EXTRA_DIST = 2321 2322 CLEANFILES = 2323 MOSTLYCLEANFILES = 2324 2325 include libltdl/Makefile.inc 2326 2327 2328`--quiet' 2329`-q' 2330 Work silently. `libtoolize --quiet' is used by GNU Automake to 2331 add libtool files to your package if necessary. 2332 2333`--recursive' 2334 If passed in conjunction with `--ltdl', this option will cause the 2335 `libtoolize' installed `libltdl' to be set up for use with a 2336 recursive `automake' build. To make use of it, you will need to 2337 adjust the parent project's `configure.ac': 2338 2339 AC_CONFIG_FILES([libltdl/Makefile]) 2340 2341 and `Makefile.am': 2342 2343 SUBDIRS += libltdl 2344 2345`--subproject' 2346 If passed in conjunction with `--ltdl', this option will cause the 2347 `libtoolize' installed `libltdl' to be set up for independent 2348 configuration and compilation as a self-contained subproject. To 2349 make use of it, you should arrange for your build to call 2350 `libltdl/configure', and then run `make' in the `libltdl' 2351 directory (or the subdirectory you put libltdl into). If your 2352 project uses Autoconf, you can use the supplied `LT_WITH_LTDL' 2353 macro, or else call `AC_CONFIG_SUBDIRS' directly. 2354 2355 Previous releases of `libltdl' built exclusively in this mode, but 2356 now it is the default mode both for backwards compatibility and 2357 because, for example, it is suitable for use in projects that wish 2358 to use `libltdl', but not use the Autotools for their own build 2359 process. 2360 2361`--verbose' 2362`-v' 2363 Work noisily! Give a blow by blow account of what `libtoolize' is 2364 doing. 2365 2366`--version' 2367 Print `libtoolize' version information and exit. 2368 2369 Sometimes it can be useful to pass options to `libtoolize' even 2370though it is called by another program, such as `autoreconf'. A 2371limited number of options are parsed from the environment variable 2372`LIBTOOLIZE_OPTIONS': currently `--debug', `--no-warn', `--quiet' and 2373`--verbose'. Multiple options passed in `LIBTOOLIZE_OPTIONS' must be 2374separated with a space, comma or a colon. 2375 2376 By default, a warning is issued for unknown options found in 2377`LIBTOOLIZE_OPTIONS' unless the first such option is `--no-warn'. 2378Where `libtoolize' has always quit on receipt of an unknown option at 2379the command line, this and all previous releases of `libtoolize' will 2380continue unabated whatever the content of `LIBTOOLIZE_OPTIONS' (modulo 2381some possible warning messages). 2382 2383 trick$ LIBTOOLIZE_OPTIONS=--no-warn,--quiet autoreconf --install 2384 2385 If `libtoolize' detects an explicit call to `AC_CONFIG_MACRO_DIR' 2386(*note The Autoconf Manual: (autoconf)Input.) in your `configure.ac', 2387it will put the Libtool macros in the specified directory. 2388 2389 In the future other Autotools will automatically check the contents 2390of `AC_CONFIG_MACRO_DIR', but at the moment it is more portable to add 2391the macro directory to `ACLOCAL_AMFLAGS' in `Makefile.am', which is 2392where the tools currently look. If `libtoolize' doesn't see 2393`AC_CONFIG_MACRO_DIR', it too will honour the first `-I' argument in 2394`ACLOCAL_AMFLAGS' when choosing a directory to store libtool 2395configuration macros in. It is perfectly sensible to use both 2396`AC_CONFIG_MACRO_DIR' and `ACLOCAL_AMFLAGS', as long as they are kept 2397in synchronisation. 2398 2399 ACLOCAL_AMFLAGS = -I m4 2400 2401 When you bootstrap your project with `aclocal', then you will need 2402to explicitly pass the same macro directory with `aclocal''s `-I' flag: 2403 2404 trick$ aclocal -I m4 2405 2406 If `libtoolize' detects an explicit call to `AC_CONFIG_AUX_DIR' 2407(*note The Autoconf Manual: (autoconf)Input.) in your `configure.ac', it 2408will put the other support files in the specified directory. Otherwise 2409they too end up in the project root directory. 2410 2411 Unless `--no-warn' is passed, `libtoolize' displays hints for adding 2412libtool support to your package, as well. 2413 2414 2415File: libtool.info, Node: Autoconf and LTLIBOBJS, Prev: Invoking libtoolize, Up: Distributing 2416 24175.5.2 Autoconf and `LTLIBOBJS' 2418------------------------------ 2419 2420People used to add code like the following to their `configure.ac': 2421 2422 LTLIBOBJS=`echo "$LIBOBJS" | sed 's/\.[^.]* /.lo /g;s/\.[^.]*$/.lo/'` 2423 AC_SUBST([LTLIBOBJS]) 2424 2425This is no longer required (since Autoconf 2.54), and doesn't take 2426Automake's deansification support into account either, so doesn't work 2427correctly even with ancient Autoconfs! 2428 2429 Provided you are using a recent (2.54 or better) incarnation of 2430Autoconf, the call to `AC_OUTPUT' takes care of setting `LTLIBOBJS' up 2431correctly, so you can simply delete such snippets from your 2432`configure.ac' if you had them. 2433 2434 2435File: libtool.info, Node: Static-only libraries, Prev: Distributing, Up: Integrating libtool 2436 24375.6 Static-only libraries 2438========================= 2439 2440When you are developing a package, it is often worthwhile to configure 2441your package with the `--disable-shared' flag, or to override the 2442defaults for `LT_INIT' by using the `disable-shared' option (*note The 2443`LT_INIT' macro: LT_INIT.). This prevents libtool from building shared 2444libraries, which has several advantages: 2445 2446 * compilation is twice as fast, which can speed up your development 2447 cycle, 2448 2449 * debugging is easier because you don't need to deal with any 2450 complexities added by shared libraries, and 2451 2452 * you can see how libtool behaves on static-only platforms. 2453 2454 You may want to put a small note in your package `README' to let 2455other developers know that `--disable-shared' can save them time. The 2456following example note is taken from the GIMP(1) distribution `README': 2457 2458 The GIMP uses GNU Libtool in order to build shared libraries on a 2459 variety of systems. While this is very nice for making usable 2460 binaries, it can be a pain when trying to debug a program. For that 2461 reason, compilation of shared libraries can be turned off by 2462 specifying the `--disable-shared' option to `configure'. 2463 2464 ---------- Footnotes ---------- 2465 2466 (1) GNU Image Manipulation Program, for those who haven't taken the 2467plunge. See `http://www.gimp.org/'. 2468 2469 2470File: libtool.info, Node: Other languages, Next: Versioning, Prev: Integrating libtool, Up: Top 2471 24726 Using libtool with other languages 2473************************************ 2474 2475Libtool was first implemented in order to add support for writing shared 2476libraries in the C language. However, over time, libtool is being 2477integrated with other languages, so that programmers are free to reap 2478the benefits of shared libraries in their favorite programming language. 2479 2480 This chapter describes how libtool interacts with other languages, 2481and what special considerations you need to make if you do not use C. 2482 2483* Menu: 2484 2485* C++ libraries:: Writing libraries for C++ 2486* Tags:: Tags 2487 2488 2489File: libtool.info, Node: C++ libraries, Next: Tags, Up: Other languages 2490 24916.1 Writing libraries for C++ 2492============================= 2493 2494Creating libraries of C++ code should be a fairly straightforward 2495process, because its object files differ from C ones in only three ways: 2496 2497 1. Because of name mangling, C++ libraries are only usable by the C++ 2498 compiler that created them. This decision was made by the 2499 designers of C++ in order to protect users from conflicting 2500 implementations of features such as constructors, exception 2501 handling, and RTTI. 2502 2503 2. On some systems, the C++ compiler must take special actions for the 2504 dynamic linker to run dynamic (i.e., run-time) initializers. This 2505 means that we should not call `ld' directly to link such 2506 libraries, and we should use the C++ compiler instead. 2507 2508 3. C++ compilers will link some Standard C++ library in by default, 2509 but libtool does not know which are these libraries, so it cannot 2510 even run the inter-library dependence analyzer to check how to 2511 link it in. Therefore, running `ld' to link a C++ program or 2512 library is deemed to fail. 2513 2514 Because of these three issues, Libtool has been designed to always 2515use the C++ compiler to compile and link C++ programs and libraries. In 2516some instances the `main()' function of a program must also be compiled 2517with the C++ compiler for static C++ objects to be properly initialized. 2518 2519 2520File: libtool.info, Node: Tags, Prev: C++ libraries, Up: Other languages 2521 25226.2 Tags 2523======== 2524 2525Libtool supports multiple languages through the use of tags. 2526Technically a tag corresponds to a set of configuration variables 2527associated with a language. These variables tell `libtool' how it 2528should create objects and libraries for each language. 2529 2530 Tags are defined at `configure'-time for each language activated in 2531the package (see `LT_LANG' in *note LT_INIT::). Here is the 2532correspondence between language names and tags names. 2533 2534Language name Tag name 2535C CC 2536C++ CXX 2537Java GCJ 2538Fortran 77 F77 2539Fortran FC 2540Windows Resource RC 2541 2542 `libtool' tries to automatically infer which tag to use from the 2543compiler command being used to compile or link. If it can't infer a 2544tag, then it defaults to the configuration for the `C' language. 2545 2546 The tag can also be specified using `libtool''s `--tag=TAG' option 2547(*note Invoking libtool::). It is a good idea to do so in `Makefile' 2548rules, because that will allow users to substitute the compiler without 2549relying on `libtool' inference heuristics. When no tag is specified, 2550`libtool' will default to `CC'; this tag always exists. 2551 2552 Finally, the set of tags available in a particular project can be 2553retrieved by tracing for the `LT_SUPPORTED_TAG' macro (*note Trace 2554interface::). 2555 2556 2557File: libtool.info, Node: Versioning, Next: Library tips, Prev: Other languages, Up: Top 2558 25597 Library interface versions 2560**************************** 2561 2562The most difficult issue introduced by shared libraries is that of 2563creating and resolving runtime dependencies. Dependencies on programs 2564and libraries are often described in terms of a single name, such as 2565`sed'. So, one may say "libtool depends on sed," and that is good 2566enough for most purposes. 2567 2568 However, when an interface changes regularly, we need to be more 2569specific: "Gnus 5.1 requires Emacs 19.28 or above." Here, the 2570description of an interface consists of a name, and a "version number." 2571 2572 Even that sort of description is not accurate enough for some 2573purposes. What if Emacs 20 changes enough to break Gnus 5.1? 2574 2575 The same problem exists in shared libraries: we require a formal 2576version system to describe the sorts of dependencies that programs have 2577on shared libraries, so that the dynamic linker can guarantee that 2578programs are linked only against libraries that provide the interface 2579they require. 2580 2581* Menu: 2582 2583* Interfaces:: What are library interfaces? 2584* Libtool versioning:: Libtool's versioning system. 2585* Updating version info:: Changing version information before releases. 2586* Release numbers:: Breaking binary compatibility for aesthetics. 2587 2588 2589File: libtool.info, Node: Interfaces, Next: Libtool versioning, Up: Versioning 2590 25917.1 What are library interfaces? 2592================================ 2593 2594Interfaces for libraries may be any of the following (and more): 2595 2596 * global variables: both names and types 2597 2598 * global functions: argument types and number, return types, and 2599 function names 2600 2601 * standard input, standard output, standard error, and file formats 2602 2603 * sockets, pipes, and other inter-process communication protocol 2604 formats 2605 2606 Note that static functions do not count as interfaces, because they 2607are not directly available to the user of the library. 2608 2609 2610File: libtool.info, Node: Libtool versioning, Next: Updating version info, Prev: Interfaces, Up: Versioning 2611 26127.2 Libtool's versioning system 2613=============================== 2614 2615Libtool has its own formal versioning system. It is not as flexible as 2616some, but it is definitely the simplest of the more powerful versioning 2617systems. 2618 2619 Think of a library as exporting several sets of interfaces, 2620arbitrarily represented by integers. When a program is linked against 2621a library, it may use any subset of those interfaces. 2622 2623 Libtool's description of the interfaces that a program uses is 2624simple: it encodes the least and the greatest interface numbers in the 2625resulting binary (FIRST-INTERFACE, LAST-INTERFACE). 2626 2627 The dynamic linker is guaranteed that if a library supports _every_ 2628interface number between FIRST-INTERFACE and LAST-INTERFACE, then the 2629program can be relinked against that library. 2630 2631 Note that this can cause problems because libtool's compatibility 2632requirements are actually stricter than is necessary. 2633 2634 Say `libhello' supports interfaces 5, 16, 17, 18, and 19, and that 2635libtool is used to link `test' against `libhello'. 2636 2637 Libtool encodes the numbers 5 and 19 in `test', and the dynamic 2638linker will only link `test' against libraries that support _every_ 2639interface between 5 and 19. So, the dynamic linker refuses to link 2640`test' against `libhello'! 2641 2642 In order to eliminate this problem, libtool only allows libraries to 2643declare consecutive interface numbers. So, `libhello' can declare at 2644most that it supports interfaces 16 through 19. Then, the dynamic 2645linker will link `test' against `libhello'. 2646 2647 So, libtool library versions are described by three integers: 2648 2649CURRENT 2650 The most recent interface number that this library implements. 2651 2652REVISION 2653 The implementation number of the CURRENT interface. 2654 2655AGE 2656 The difference between the newest and oldest interfaces that this 2657 library implements. In other words, the library implements all the 2658 interface numbers in the range from number `CURRENT - AGE' to 2659 `CURRENT'. 2660 2661 If two libraries have identical CURRENT and AGE numbers, then the 2662dynamic linker chooses the library with the greater REVISION number. 2663 2664 2665File: libtool.info, Node: Updating version info, Next: Release numbers, Prev: Libtool versioning, Up: Versioning 2666 26677.3 Updating library version information 2668======================================== 2669 2670If you want to use libtool's versioning system, then you must specify 2671the version information to libtool using the `-version-info' flag 2672during link mode (*note Link mode::). 2673 2674 This flag accepts an argument of the form 2675`CURRENT[:REVISION[:AGE]]'. So, passing `-version-info 3:12:1' sets 2676CURRENT to 3, REVISION to 12, and AGE to 1. 2677 2678 If either REVISION or AGE are omitted, they default to 0. Also note 2679that AGE must be less than or equal to the CURRENT interface number. 2680 2681 Here are a set of rules to help you update your library version 2682information: 2683 2684 1. Start with version information of `0:0:0' for each libtool library. 2685 2686 2. Update the version information only immediately before a public 2687 release of your software. More frequent updates are unnecessary, 2688 and only guarantee that the current interface number gets larger 2689 faster. 2690 2691 3. If the library source code has changed at all since the last 2692 update, then increment REVISION (`C:R:A' becomes `C:r+1:A'). 2693 2694 4. If any interfaces have been added, removed, or changed since the 2695 last update, increment CURRENT, and set REVISION to 0. 2696 2697 5. If any interfaces have been added since the last public release, 2698 then increment AGE. 2699 2700 6. If any interfaces have been removed or changed since the last 2701 public release, then set AGE to 0. 2702 2703 *_Never_* try to set the interface numbers so that they correspond 2704to the release number of your package. This is an abuse that only 2705fosters misunderstanding of the purpose of library versions. Instead, 2706use the `-release' flag (*note Release numbers::), but be warned that 2707every release of your package will not be binary compatible with any 2708other release. 2709 2710 The following explanation may help to understand the above rules a 2711bit better: consider that there are three possible kinds of reactions 2712from users of your library to changes in a shared library: 2713 2714 1. Programs using the previous version may use the new version as 2715 drop-in replacement, and programs using the new version can also 2716 work with the previous one. In other words, no recompiling nor 2717 relinking is needed. In this case, bump REVISION only, don't touch 2718 CURRENT nor AGE. 2719 2720 2. Programs using the previous version may use the new version as 2721 drop-in replacement, but programs using the new version may use 2722 APIs not present in the previous one. In other words, a program 2723 linking against the new version may fail with "unresolved symbols" 2724 if linking against the old version at runtime: set REVISION to 0, 2725 bump CURRENT and AGE. 2726 2727 3. Programs may need to be changed, recompiled, relinked in order to 2728 use the new version. Bump CURRENT, set REVISION and AGE to 0. 2729 2730In the above description, _programs_ using the library in question may 2731also be replaced by other libraries using it. 2732 2733 2734File: libtool.info, Node: Release numbers, Prev: Updating version info, Up: Versioning 2735 27367.4 Managing release information 2737================================ 2738 2739Often, people want to encode the name of the package release into the 2740shared library so that it is obvious to the user which package their 2741programs are linked against. This convention is used especially on 2742GNU/Linux: 2743 2744 trick$ ls /usr/lib/libbfd* 2745 /usr/lib/libbfd.a /usr/lib/libbfd.so.2.7.0.2 2746 /usr/lib/libbfd.so 2747 trick$ 2748 2749 On `trick', `/usr/lib/libbfd.so' is a symbolic link to 2750`libbfd.so.2.7.0.2', which was distributed as a part of 2751`binutils-2.7.0.2'. 2752 2753 Unfortunately, this convention conflicts directly with libtool's 2754idea of library interface versions, because the library interface 2755rarely changes at the same time that the release number does, and the 2756library suffix is never the same across all platforms. 2757 2758 So, in order to accommodate both views, you can use the `-release' 2759flag in order to set release information for libraries for which you do 2760not want to use `-version-info'. For the `libbfd' example, the next 2761release that uses libtool should be built with `-release 2.9.0', which 2762will produce the following files on GNU/Linux: 2763 2764 trick$ ls /usr/lib/libbfd* 2765 /usr/lib/libbfd-2.9.0.so /usr/lib/libbfd.a 2766 /usr/lib/libbfd.so 2767 trick$ 2768 2769 In this case, `/usr/lib/libbfd.so' is a symbolic link to 2770`libbfd-2.9.0.so'. This makes it obvious that the user is dealing with 2771`binutils-2.9.0', without compromising libtool's idea of interface 2772versions. 2773 2774 Note that this option causes a modification of the library name, so 2775do not use it unless you want to break binary compatibility with any 2776past library releases. In general, you should only use `-release' for 2777package-internal libraries or for ones whose interfaces change very 2778frequently. 2779 2780 2781File: libtool.info, Node: Library tips, Next: Inter-library dependencies, Prev: Versioning, Up: Top 2782 27838 Tips for interface design 2784*************************** 2785 2786Writing a good library interface takes a lot of practice and thorough 2787understanding of the problem that the library is intended to solve. 2788 2789 If you design a good interface, it won't have to change often, you 2790won't have to keep updating documentation, and users won't have to keep 2791relearning how to use the library. 2792 2793 Here is a brief list of tips for library interface design that may 2794help you in your exploits: 2795 2796Plan ahead 2797 Try to make every interface truly minimal, so that you won't need 2798 to delete entry points very often. 2799 2800Avoid interface changes 2801 Some people love redesigning and changing entry points just for 2802 the heck of it (note: _renaming_ a function is considered changing 2803 an entry point). Don't be one of those people. If you must 2804 redesign an interface, then try to leave compatibility functions 2805 behind so that users don't need to rewrite their existing code. 2806 2807Use opaque data types 2808 The fewer data type definitions a library user has access to, the 2809 better. If possible, design your functions to accept a generic 2810 pointer (that you can cast to an internal data type), and provide 2811 access functions rather than allowing the library user to directly 2812 manipulate the data. That way, you have the freedom to change the 2813 data structures without changing the interface. 2814 2815 This is essentially the same thing as using abstract data types and 2816 inheritance in an object-oriented system. 2817 2818Use header files 2819 If you are careful to document each of your library's global 2820 functions and variables in header files, and include them in your 2821 library source files, then the compiler will let you know if you 2822 make any interface changes by accident (*note C header files::). 2823 2824Use the `static' keyword (or equivalent) whenever possible 2825 The fewer global functions your library has, the more flexibility 2826 you'll have in changing them. Static functions and variables may 2827 change forms as often as you like... your users cannot access 2828 them, so they aren't interface changes. 2829 2830Be careful with array dimensions 2831 The number of elements in a global array is part of an interface, 2832 even if the header just declares `extern int foo[];'. This is 2833 because on i386 and some other SVR4/ELF systems, when an 2834 application references data in a shared library the size of that 2835 data (whatever its type) is included in the application 2836 executable. If you might want to change the size of an array or 2837 string then provide a pointer not the actual array. 2838 2839* Menu: 2840 2841* C header files:: How to write portable include files. 2842 2843 2844File: libtool.info, Node: C header files, Up: Library tips 2845 28468.1 Writing C header files 2847========================== 2848 2849Writing portable C header files can be difficult, since they may be read 2850by different types of compilers: 2851 2852C++ compilers 2853 C++ compilers require that functions be declared with full 2854 prototypes, since C++ is more strongly typed than C. C functions 2855 and variables also need to be declared with the `extern "C"' 2856 directive, so that the names aren't mangled. *Note C++ 2857 libraries::, for other issues relevant to using C++ with libtool. 2858 2859ANSI C compilers 2860 ANSI C compilers are not as strict as C++ compilers, but functions 2861 should be prototyped to avoid unnecessary warnings when the header 2862 file is `#include'd. 2863 2864non-ANSI C compilers 2865 Non-ANSI compilers will report errors if functions are prototyped. 2866 2867 These complications mean that your library interface headers must use 2868some C preprocessor magic in order to be usable by each of the above 2869compilers. 2870 2871 `foo.h' in the `tests/demo' subdirectory of the libtool distribution 2872serves as an example for how to write a header file that can be safely 2873installed in a system directory. 2874 2875 Here are the relevant portions of that file: 2876 2877 /* BEGIN_C_DECLS should be used at the beginning of your declarations, 2878 so that C++ compilers don't mangle their names. Use END_C_DECLS at 2879 the end of C declarations. */ 2880 #undef BEGIN_C_DECLS 2881 #undef END_C_DECLS 2882 #ifdef __cplusplus 2883 # define BEGIN_C_DECLS extern "C" { 2884 # define END_C_DECLS } 2885 #else 2886 # define BEGIN_C_DECLS /* empty */ 2887 # define END_C_DECLS /* empty */ 2888 #endif 2889 2890 /* PARAMS is a macro used to wrap function prototypes, so that 2891 compilers that don't understand ANSI C prototypes still work, 2892 and ANSI C compilers can issue warnings about type mismatches. */ 2893 #undef PARAMS 2894 #if defined (__STDC__) || defined (_AIX) \ 2895 || (defined (__mips) && defined (_SYSTYPE_SVR4)) \ 2896 || defined(WIN32) || defined(__cplusplus) 2897 # define PARAMS(protos) protos 2898 #else 2899 # define PARAMS(protos) () 2900 #endif 2901 2902 These macros are used in `foo.h' as follows: 2903 2904 #ifndef FOO_H 2905 #define FOO_H 1 2906 2907 /* The above macro definitions. */ 2908 #include "..." 2909 2910 BEGIN_C_DECLS 2911 2912 int foo PARAMS((void)); 2913 int hello PARAMS((void)); 2914 2915 END_C_DECLS 2916 2917 #endif /* !FOO_H */ 2918 2919 Note that the `#ifndef FOO_H' prevents the body of `foo.h' from 2920being read more than once in a given compilation. 2921 2922 Also the only thing that must go outside the 2923`BEGIN_C_DECLS'/`END_C_DECLS' pair are `#include' lines. Strictly 2924speaking it is only C symbol names that need to be protected, but your 2925header files will be more maintainable if you have a single pair of 2926these macros around the majority of the header contents. 2927 2928 You should use these definitions of `PARAMS', `BEGIN_C_DECLS', and 2929`END_C_DECLS' into your own headers. Then, you may use them to create 2930header files that are valid for C++, ANSI, and non-ANSI compilers(1). 2931 2932 Do not be naive about writing portable code. Following the tips 2933given above will help you miss the most obvious problems, but there are 2934definitely other subtle portability issues. You may need to cope with 2935some of the following issues: 2936 2937 * Pre-ANSI compilers do not always support the `void *' generic 2938 pointer type, and so need to use `char *' in its place. 2939 2940 * The `const', `inline' and `signed' keywords are not supported by 2941 some compilers, especially pre-ANSI compilers. 2942 2943 * The `long double' type is not supported by many compilers. 2944 2945 ---------- Footnotes ---------- 2946 2947 (1) We used to recommend `__P', `__BEGIN_DECLS' and `__END_DECLS'. 2948This was bad advice since symbols (even preprocessor macro names) that 2949begin with an underscore are reserved for the use of the compiler. 2950 2951 2952File: libtool.info, Node: Inter-library dependencies, Next: Dlopened modules, Prev: Library tips, Up: Top 2953 29549 Inter-library dependencies 2955**************************** 2956 2957By definition, every shared library system provides a way for 2958executables to depend on libraries, so that symbol resolution is 2959deferred until runtime. 2960 2961 An "inter-library dependency" is one in which a library depends on 2962other libraries. For example, if the libtool library `libhello' uses 2963the `cos' function, then it has an inter-library dependency on `libm', 2964the math library that implements `cos'. 2965 2966 Some shared library systems provide this feature in an 2967internally-consistent way: these systems allow chains of dependencies of 2968potentially infinite length. 2969 2970 However, most shared library systems are restricted in that they only 2971allow a single level of dependencies. In these systems, programs may 2972depend on shared libraries, but shared libraries may not depend on other 2973shared libraries. 2974 2975 In any event, libtool provides a simple mechanism for you to declare 2976inter-library dependencies: for every library `libNAME' that your own 2977library depends on, simply add a corresponding `-lNAME' option to the 2978link line when you create your library. To make an example of our 2979`libhello' that depends on `libm': 2980 2981 burger$ libtool --mode=link gcc -g -O -o libhello.la foo.lo hello.lo \ 2982 -rpath /usr/local/lib -lm 2983 burger$ 2984 2985 When you link a program against `libhello', you don't need to 2986specify the same `-l' options again: libtool will do that for you, in 2987order to guarantee that all the required libraries are found. This 2988restriction is only necessary to preserve compatibility with static 2989library systems and simple dynamic library systems. 2990 2991 Some platforms, such as AIX, do not even allow you this flexibility. 2992In order to build a shared library, it must be entirely self-contained 2993(that is, have references only to symbols that are found in the `.lo' 2994files or the specified `-l' libraries), and you need to specify the 2995`-no-undefined' flag. By default, libtool builds only static libraries 2996on these kinds of platforms. 2997 2998 The simple-minded inter-library dependency tracking code of libtool 2999releases prior to 1.2 was disabled because it was not clear when it was 3000possible to link one library with another, and complex failures would 3001occur. A more complex implementation of this concept was re-introduced 3002before release 1.3, but it has not been ported to all platforms that 3003libtool supports. The default, conservative behavior is to avoid 3004linking one library with another, introducing their inter-dependencies 3005only when a program is linked with them. 3006 3007 3008File: libtool.info, Node: Dlopened modules, Next: Using libltdl, Prev: Inter-library dependencies, Up: Top 3009 301010 Dlopened modules 3011******************* 3012 3013It can sometimes be confusing to discuss "dynamic linking", because the 3014term is used to refer to two different concepts: 3015 3016 1. Compiling and linking a program against a shared library, which is 3017 resolved automatically at run time by the dynamic linker. In this 3018 process, dynamic linking is transparent to the application. 3019 3020 2. The application calling functions such as `dlopen' that load 3021 arbitrary, user-specified modules at runtime. This type of dynamic 3022 linking is explicitly controlled by the application. 3023 3024 To mitigate confusion, this manual refers to the second type of 3025dynamic linking as "dlopening" a module. 3026 3027 The main benefit to dlopening object modules is the ability to access 3028compiled object code to extend your program, rather than using an 3029interpreted language. In fact, dlopen calls are frequently used in 3030language interpreters to provide an efficient way to extend the 3031language. 3032 3033 As of version 2.2.10, libtool provides support for dlopened modules. 3034However, you should indicate that your package is willing to use such 3035support, by using the `LT_INIT' option `dlopen' in `configure.ac'. If 3036this option is not given, libtool will assume no dlopening mechanism is 3037available, and will try to simulate it. 3038 3039 This chapter discusses how you as a dlopen application developer 3040might use libtool to generate dlopen-accessible modules. 3041 3042* Menu: 3043 3044* Building modules:: Creating dlopenable objects and libraries. 3045* Dlpreopening:: Dlopening that works on static platforms. 3046* Linking with dlopened modules:: Using dlopenable modules in libraries. 3047* Finding the dlname:: Choosing the right file to `dlopen'. 3048* Dlopen issues:: Unresolved problems that need your attention. 3049 3050 3051File: libtool.info, Node: Building modules, Next: Dlpreopening, Up: Dlopened modules 3052 305310.1 Building modules to dlopen 3054=============================== 3055 3056On some operating systems, a program symbol must be specially declared 3057in order to be dynamically resolved with the `dlsym' (or equivalent) 3058function. Libtool provides the `-export-dynamic' and `-module' link 3059flags (*note Link mode::), for you to make that declaration. You need 3060to use these flags if you are linking an application program that 3061dlopens other modules or a libtool library that will also be dlopened. 3062 3063 For example, if we wanted to build a shared library, `hello', that 3064would later be dlopened by an application, we would add `-module' to 3065the other link flags: 3066 3067 burger$ libtool --mode=link gcc -module -o hello.la foo.lo \ 3068 hello.lo -rpath /usr/local/lib -lm 3069 burger$ 3070 3071 If symbols from your _executable_ are needed to satisfy unresolved 3072references in a library you want to dlopen you will have to use the flag 3073`-export-dynamic'. You should use `-export-dynamic' while linking the 3074executable that calls dlopen: 3075 3076 burger$ libtool --mode=link gcc -export-dynamic -o helldl main.o 3077 burger$ 3078 3079 3080File: libtool.info, Node: Dlpreopening, Next: Linking with dlopened modules, Prev: Building modules, Up: Dlopened modules 3081 308210.2 Dlpreopening 3083================= 3084 3085Libtool provides special support for dlopening libtool object and 3086libtool library files, so that their symbols can be resolved _even on 3087platforms without any `dlopen' and `dlsym' functions_. 3088 3089 Consider the following alternative ways of loading code into your 3090program, in order of increasing "laziness": 3091 3092 1. Linking against object files that become part of the program 3093 executable, whether or not they are referenced. If an object file 3094 cannot be found, then the compile time linker refuses to create 3095 the executable. 3096 3097 2. Declaring a static library to the linker, so that it is searched 3098 at link time in order to satisfy any undefined references in the 3099 above object files. If the static library cannot be found, then 3100 the compile time linker refuses to create the executable. 3101 3102 3. Declaring a shared library to the runtime linker, so that it is 3103 searched at runtime in order to satisfy any undefined references 3104 in the above files. If the shared library cannot be found, then 3105 the dynamic linker aborts the program before it runs. 3106 3107 4. Dlopening a module, so that the application can resolve its own, 3108 dynamically-computed references. If there is an error opening the 3109 module, or the module is not found, then the application can 3110 recover without crashing. 3111 3112 Libtool emulates `-dlopen' on static platforms by linking objects 3113into the program at compile time, and creating data structures that 3114represent the program's symbol table. In order to use this feature, 3115you must declare the objects you want your application to dlopen by 3116using the `-dlopen' or `-dlpreopen' flags when you link your program 3117(*note Link mode::). 3118 3119 -- Data Type: lt_dlsymlist typedef struct { const char *NAME; 3120 void *ADDRESS; } lt_dlsymlist 3121 The NAME attribute is a null-terminated character string of the 3122 symbol name, such as `"fprintf"'. The ADDRESS attribute is a 3123 generic pointer to the appropriate object, such as `&fprintf'. 3124 3125 -- Variable: const lt_dlsymlist lt_preloaded_symbols[] 3126 An array of LT_DLSYMLIST structures, representing all the preloaded 3127 symbols linked into the program proper. For each module 3128 `-dlpreopen'ed by the Libtool linked program there is an element 3129 with the NAME of the module and an ADDRESS of `0', followed by all 3130 symbols exported from this file. For the executable itself the 3131 special name `@PROGRAM@' is used. The last element of all has a 3132 NAME and ADDRESS of `0'. 3133 3134 To facilitate inclusion of symbol lists into libraries, 3135 `lt_preloaded_symbols' is `#define'd to a suitably unique name in 3136 `ltdl.h'. 3137 3138 Some compilers may allow identifiers that are not valid in ANSI C, 3139such as dollar signs. Libtool only recognizes valid ANSI C symbols (an 3140initial ASCII letter or underscore, followed by zero or more ASCII 3141letters, digits, and underscores), so non-ANSI symbols will not appear 3142in LT_PRELOADED_SYMBOLS. 3143 3144 -- Function: int lt_dlpreload (const lt_dlsymlist *PRELOADED) 3145 Register the list of preloaded modules PRELOADED. If PRELOADED is 3146 `NULL', then all previously registered symbol lists, except the 3147 list set by `lt_dlpreload_default', are deleted. Return 0 on 3148 success. 3149 3150 -- Function: int lt_dlpreload_default (const lt_dlsymlist *PRELOADED) 3151 Set the default list of preloaded modules to PRELOADED, which 3152 won't be deleted by `lt_dlpreload'. Note that this function does 3153 _not_ require libltdl to be initialized using `lt_dlinit' and can 3154 be used in the program to register the default preloaded modules. 3155 Instead of calling this function directly, most programs will use 3156 the macro `LTDL_SET_PRELOADED_SYMBOLS'. 3157 3158 Return 0 on success. 3159 3160 -- Macro: LTDL_SET_PRELOADED_SYMBOLS 3161 Set the default list of preloaded symbols. Should be used in your 3162 program to initialize libltdl's list of preloaded modules. 3163 3164 #include <ltdl.h> 3165 3166 int main() { 3167 /* ... */ 3168 LTDL_SET_PRELOADED_SYMBOLS(); 3169 /* ... */ 3170 } 3171 3172 -- Function Type: int lt_dlpreload_callback_func (lt_dlhandle HANDLE) 3173 Functions of this type can be passed to `lt_dlpreload_open', which 3174 in turn will call back into a function thus passed for each 3175 preloaded module that it opens. 3176 3177 -- Function: int lt_dlpreload_open (const char *ORIGINATOR, 3178 lt_dlpreload_callback_func *FUNC) 3179 Load all of the preloaded modules for ORIGINATOR. For every 3180 module opened in this way, call FUNC. 3181 3182 To open all of the modules preloaded into `libhell.la' (presumably 3183 from within the `libhell.a' initialisation code): 3184 3185 #define preloaded_symbols lt_libhell_LTX_preloaded_symbols 3186 3187 static int hell_preload_callback (lt_dlhandle handle); 3188 3189 int 3190 hell_init (void) 3191 { 3192 ... 3193 if (lt_dlpreload (&preloaded_symbols) == 0) 3194 { 3195 lt_dlpreload_open ("libhell", preload_callback); 3196 } 3197 ... 3198 } 3199 3200 Note that to prevent clashes between multiple preloaded modules, 3201 the preloaded symbols are accessed via a mangled symbol name: to 3202 get the symbols preloaded into `libhell', you must prefix 3203 `preloaded_symbols' with `lt_'; the originator name, `libhell' in 3204 this case; and `_LTX_'. That is, 3205 `lt_libhell_LTX_preloaded_symbols' here. 3206 3207 3208File: libtool.info, Node: Linking with dlopened modules, Next: Finding the dlname, Prev: Dlpreopening, Up: Dlopened modules 3209 321010.3 Linking with dlopened modules 3211================================== 3212 3213When, say, an interpreter application uses dlopened modules to extend 3214the list of methods it provides, an obvious abstraction for the 3215maintainers of the interpreter is to have all methods (including the 3216built in ones supplied with the interpreter) accessed through dlopen. 3217For one thing, the dlopening functionality will be tested even during 3218routine invocations. For another, only one subsystem has to be written 3219for getting methods into the interpreter. 3220 3221 The downside of this abstraction is, of course, that environments 3222that provide only static linkage can't even load the intrinsic 3223interpreter methods. Not so! We can statically link those methods by 3224*dlpreopening* them. 3225 3226 Unfortunately, since platforms such as AIX and cygwin require that 3227all library symbols must be resolved at compile time, the interpreter 3228maintainers will need to provide a library to both its own dlpreopened 3229modules, and third-party modules loaded by dlopen. In itself, that is 3230not so bad, except that the interpreter too must provide those same 3231symbols otherwise it will be impossible to resolve all the symbols 3232required by the modules as they are loaded. Things are even worse if 3233the code that loads the modules for the interpreter is itself in a 3234library - and that is usually the case for any non-trivial application. 3235Modern platforms take care of this by automatically loading all of a 3236module's dependency libraries as the module is loaded (libltdl can do 3237this even on platforms that can't do it by themselves). In the end, 3238this leads to problems with duplicated symbols and prevents modules 3239from loading, and prevents the application from compiling when modules 3240are preloaded. 3241 3242 ,-------------. ,------------------. ,-----------------. 3243 | Interpreter |----> Module------------> Third-party | 3244 `-------------' | Loader | |Dlopened Modules | 3245 | | | `-----------------' 3246 |,-------v--------.| | 3247 || Dlpreopened || | 3248 || Modules || | 3249 |`----------------'| | 3250 | | | | 3251 |,-------v--------.| ,--------v--------. 3252 ||Module Interface|| |Module Interface | 3253 || Library || | Library | 3254 |`----------------'| `-----------------' 3255 `------------------' 3256 3257 Libtool has the concept of "weak library interfaces" to circumvent 3258this problem. Recall that the code that dlopens method-provider 3259modules for the interpreter application resides in a library: All of 3260the modules and the dlopener library itself should be linked against 3261the common library that resolves the module symbols at compile time. 3262To guard against duplicate symbol definitions, and for dlpreopened 3263modules to work at all in this scenario, the dlopener library must 3264declare that it provides a weak library interface to the common symbols 3265in the library it shares with the modules. That way, when `libtool' 3266links the *Module Loader* library with some *Dlpreopened Modules* that 3267were in turn linked against the *Module Interface Library*, it knows 3268that the *Module Loader* provides an already loaded *Module Interface 3269Library* to resolve symbols for the *Dlpreopened Modules*, and doesn't 3270ask the compiler driver to link an identical *Module Interface Library* 3271dependency library too. 3272 3273 In conjunction with Automake, the `Makefile.am' for the *Module 3274Loader* might look like this: 3275 3276 lib_LTLIBRARIES = libinterface.la libloader.la 3277 3278 libinterface_la_SOURCES = interface.c interface.h 3279 libinterface_la_LDFLAGS = -version-info 3:2:1 3280 3281 libloader_la_SOURCES = loader.c 3282 libloader_la_LDFLAGS = -weak libinterface.la \ 3283 -version-info 3:2:1 \ 3284 -dlpreopen ../modules/intrinsics.la 3285 libloader_la_LIBADD = $(libinterface_la_OBJECTS) 3286 3287 And the `Makefile.am' for the `intrinsics.la' module in a sibling 3288`modules' directory might look like this: 3289 3290 AM_CPPFLAGS = -I$(srcdir)/../libloader 3291 AM_LDFLAGS = -no-undefined -module -avoid-version \ 3292 -export-dynamic 3293 3294 noinst_LTLIBRARIES = intrinsics.la 3295 3296 intrinsics_la_LIBADD = ../libloader/libinterface.la 3297 3298 ../libloader/libinterface.la: 3299 cd ../libloader && $(MAKE) $(AM_MAKEFLAGS) libinterface.la 3300 3301 For a more complex example, see the sources of `libltdl' in the 3302Libtool distribution, which is built with the help of the `-weak' 3303option. 3304 3305 3306File: libtool.info, Node: Finding the dlname, Next: Dlopen issues, Prev: Linking with dlopened modules, Up: Dlopened modules 3307 330810.4 Finding the correct name to dlopen 3309======================================= 3310 3311After a library has been linked with `-module', it can be dlopened. 3312Unfortunately, because of the variation in library names, your package 3313needs to determine the correct file to dlopen. 3314 3315 The most straightforward and flexible implementation is to determine 3316the name at runtime, by finding the installed `.la' file, and searching 3317it for the following lines: 3318 3319 # The name that we can `dlopen'. 3320 dlname='DLNAME' 3321 3322 If DLNAME is empty, then the library cannot be dlopened. Otherwise, 3323it gives the dlname of the library. So, if the library was installed 3324as `/usr/local/lib/libhello.la', and the DLNAME was `libhello.so.3', 3325then `/usr/local/lib/libhello.so.3' should be dlopened. 3326 3327 If your program uses this approach, then it should search the 3328directories listed in the `LD_LIBRARY_PATH'(1) environment variable, as 3329well as the directory where libraries will eventually be installed. 3330Searching this variable (or equivalent) will guarantee that your 3331program can find its dlopened modules, even before installation, 3332provided you have linked them using libtool. 3333 3334 ---------- Footnotes ---------- 3335 3336 (1) `LIBPATH' on AIX, and `SHLIB_PATH' on HP-UX. 3337 3338 3339File: libtool.info, Node: Dlopen issues, Prev: Finding the dlname, Up: Dlopened modules 3340 334110.5 Unresolved dlopen issues 3342============================= 3343 3344The following problems are not solved by using libtool's dlopen support: 3345 3346 * Dlopen functions are generally only available on shared library 3347 platforms. If you want your package to be portable to static 3348 platforms, you have to use either libltdl (*note Using libltdl::) 3349 or develop your own alternatives to dlopening dynamic code. Most 3350 reasonable solutions involve writing wrapper functions for the 3351 `dlopen' family, which do package-specific tricks when dlopening 3352 is unsupported or not available on a given platform. 3353 3354 * There are major differences in implementations of the `dlopen' 3355 family of functions. Some platforms do not even use the same 3356 function names (notably HP-UX, with its `shl_load' family). 3357 3358 * The application developer must write a custom search function in 3359 order to discover the correct module filename to supply to 3360 `dlopen'. 3361 3362 3363File: libtool.info, Node: Using libltdl, Next: Trace interface, Prev: Dlopened modules, Up: Top 3364 336511 Using libltdl 3366**************** 3367 3368Libtool provides a small library, called `libltdl', that aims at hiding 3369the various difficulties of dlopening libraries from programmers. It 3370consists of a few headers and small C source files that can be 3371distributed with applications that need dlopening functionality. On 3372some platforms, whose dynamic linkers are too limited for a simple 3373implementation of `libltdl' services, it requires GNU DLD, or it will 3374only emulate dynamic linking with libtool's dlpreopening mechanism. 3375 3376libltdl supports currently the following dynamic linking mechanisms: 3377 3378 * `dlopen' (Solaris, Linux and various BSD flavors) 3379 3380 * `shl_load' (HP-UX) 3381 3382 * `LoadLibrary' (Win16 and Win32) 3383 3384 * `load_add_on' (BeOS) 3385 3386 * `NSAddImage' or `NSLinkModule' (Darwin and Mac OS X) 3387 3388 * GNU DLD (emulates dynamic linking for static libraries) 3389 3390 * libtool's dlpreopen (see *note Dlpreopening::) 3391 3392libltdl is licensed under the terms of the GNU Lesser General Public 3393License, with the following exception: 3394 3395 As a special exception to the GNU Lesser General Public License, 3396 if you distribute this file as part of a program or library that 3397 is built using GNU Libtool, you may include it under the same 3398 distribution terms that you use for the rest of that program. 3399 3400* Menu: 3401 3402* Libltdl interface:: How to use libltdl in your programs. 3403* Modules for libltdl:: Creating modules that can be `dlopen'ed. 3404* Thread Safety in libltdl:: Registering callbacks for multi-thread safety. 3405* User defined module data:: Associating data with loaded modules. 3406* Module loaders for libltdl:: Creating user defined module loaders. 3407* Distributing libltdl:: How to distribute libltdl with your package. 3408 3409 3410File: libtool.info, Node: Libltdl interface, Next: Modules for libltdl, Up: Using libltdl 3411 341211.1 How to use libltdl in your programs 3413======================================== 3414 3415The libltdl API is similar to the dlopen interface of Solaris and Linux, 3416which is very simple but powerful. 3417 3418To use libltdl in your program you have to include the header file 3419`ltdl.h': 3420 3421 #include <ltdl.h> 3422 3423The early releases of libltdl used some symbols that violated the POSIX 3424namespace conventions. These symbols are now deprecated, and have been 3425replaced by those described here. If you have code that relies on the 3426old deprecated symbol names, defining `LT_NON_POSIX_NAMESPACE' before 3427you include `ltdl.h' provides conversion macros. Whichever set of 3428symbols you use, the new API is not binary compatible with the last, so 3429you will need to recompile your application in order to use this 3430version of libltdl. 3431 3432Note that libltdl is not well tested in a multithreaded environment, 3433though the intention is that it should work (*note Using libltdl in a 3434multi threaded environment: Thread Safety in libltdl.). It was 3435reported that GNU/Linux's glibc 2.0's `dlopen' with `RTLD_LAZY' (which 3436libltdl uses by default) is not thread-safe, but this problem is 3437supposed to be fixed in glibc 2.1. On the other hand, `RTLD_NOW' was 3438reported to introduce problems in multi-threaded applications on 3439FreeBSD. Working around these problems is left as an exercise for the 3440reader; contributions are certainly welcome. 3441 3442The following macros are defined by including `ltdl.h': 3443 3444 -- Macro: LT_PATHSEP_CHAR 3445 `LT_PATHSEP_CHAR' is the system-dependent path separator, that is, 3446 `;' on Windows and `:' everywhere else. 3447 3448 -- Macro: LT_DIRSEP_CHAR 3449 If `LT_DIRSEP_CHAR' is defined, it can be used as directory 3450 separator in addition to `/'. On Windows, this contains `\'. 3451 3452The following types are defined in `ltdl.h': 3453 3454 -- Type: lt_dlhandle 3455 `lt_dlhandle' is a module "handle". Every lt_dlopened module has 3456 a handle associated with it. 3457 3458 -- Type: lt_dladvise 3459 `lt_dladvise' is used to control optional module loading modes. 3460 If it is not used, the default mode of the underlying system module 3461 loader is used. 3462 3463 -- Type: lt_dlsymlist 3464 `lt_dlsymlist' is a symbol list for dlpreopened modules. This 3465 structure is described in *note Dlpreopening::. 3466 3467libltdl provides the following functions: 3468 3469 -- Function: int lt_dlinit (void) 3470 Initialize libltdl. This function must be called before using 3471 libltdl and may be called several times. Return 0 on success, 3472 otherwise the number of errors. 3473 3474 -- Function: int lt_dlexit (void) 3475 Shut down libltdl and close all modules. This function will only 3476 then shut down libltdl when it was called as many times as 3477 `lt_dlinit' has been successfully called. Return 0 on success, 3478 otherwise the number of errors. 3479 3480 -- Function: lt_dlhandle lt_dlopen (const char *FILENAME) 3481 Open the module with the file name FILENAME and return a handle 3482 for it. `lt_dlopen' is able to open libtool dynamic modules, 3483 preloaded static modules, the program itself and native dynamic 3484 modules(1). 3485 3486 Unresolved symbols in the module are resolved using its dependency 3487 libraries and previously dlopened modules. If the executable using 3488 this module was linked with the `-export-dynamic' flag, then the 3489 global symbols in the executable will also be used to resolve 3490 references in the module. 3491 3492 If FILENAME is `NULL' and the program was linked with 3493 `-export-dynamic' or `-dlopen self', `lt_dlopen' will return a 3494 handle for the program itself, which can be used to access its 3495 symbols. 3496 3497 If libltdl cannot find the library and the file name FILENAME does 3498 not have a directory component it will additionally look in the 3499 following search paths for the module (in the following order): 3500 3501 1. user-defined search path: This search path can be changed by 3502 the program using the functions `lt_dlsetsearchpath', 3503 `lt_dladdsearchdir' and `lt_dlinsertsearchdir'. 3504 3505 2. libltdl's search path: This search path is the value of the 3506 environment variable LTDL_LIBRARY_PATH. 3507 3508 3. system library search path: The system dependent library 3509 search path (e.g. on Linux it is LD_LIBRARY_PATH). 3510 3511 Each search path must be a list of absolute directories separated 3512 by `LT_PATHSEP_CHAR', for example, `"/usr/lib/mypkg:/lib/foo"'. 3513 The directory names may not contain the path separator. 3514 3515 If the same module is loaded several times, the same handle is 3516 returned. If `lt_dlopen' fails for any reason, it returns `NULL'. 3517 3518 -- Function: lt_dlhandle lt_dlopenext (const char *FILENAME) 3519 The same as `lt_dlopen', except that it tries to append different 3520 file name extensions to the file name. If the file with the file 3521 name FILENAME cannot be found libltdl tries to append the 3522 following extensions: 3523 3524 1. the libtool archive extension `.la' 3525 3526 2. the extension used for native dynamically loadable modules on 3527 the host platform, e.g., `.so', `.sl', etc. 3528 3529 This lookup strategy was designed to allow programs that don't 3530 have knowledge about native dynamic libraries naming conventions 3531 to be able to `dlopen' such libraries as well as libtool modules 3532 transparently. 3533 3534 -- Function: lt_dlhandle lt_dlopenadvise (const char *FILENAME, 3535 lt_dladvise ADVISE) 3536 The same as `lt_dlopen', except that it also requires an additional 3537 argument which may contain additional hints to the underlying 3538 system module loader. The ADVISE parameter is opaque and can only 3539 be accessed with the functions documented below. 3540 3541 Note that this function does not change the content of ADVISE, so 3542 unlike the other calls in this API takes a direct `lt_dladvise' 3543 type, and not a pointer to the same. 3544 3545 -- Function: int lt_dladvise_init (lt_dladvise *ADVISE) 3546 The ADVISE parameter can be used to pass hints to the module 3547 loader when using `lt_dlopenadvise' to perform the loading. The 3548 ADVISE parameter needs to be initialised by this function before 3549 it can be used. Any memory used by ADVISE needs to be recycled 3550 with `lt_dladvise_destroy' when it is no longer needed. 3551 3552 On failure, `lt_dladvise_init' returns non-zero and sets an error 3553 message that can be retrieved with `lt_dlerror'. 3554 3555 -- Function: int lt_dladvise_destroy (lt_dladvise *ADVISE) 3556 Recycle the memory used by ADVISE. For an example, see the 3557 documentation for `lt_dladvise_ext'. 3558 3559 On failure, `lt_dladvise_destroy' returns non-zero and sets an 3560 error message that can be retrieved with `lt_dlerror'. 3561 3562 -- Function: int lt_dladvise_ext (lt_dladvise *ADVISE) 3563 Set the `ext' hint on ADVISE. Passing an ADVISE parameter to 3564 `lt_dlopenadvise' with this hint set causes it to try to append 3565 different file name extensions like `lt_dlopenext'. 3566 3567 The following example is equivalent to calling `lt_dlopenext 3568 (filename)': 3569 3570 lt_dlhandle 3571 my_dlopenext (const char *filename) 3572 { 3573 lt_dlhandle handle = 0; 3574 lt_dladvise advise; 3575 3576 if (!lt_dladvise_init (&advise) && !lt_dladvise_ext (&advise)) 3577 handle = lt_dlopenadvise (filename, advise); 3578 3579 lt_dladvise_destroy (&advise); 3580 3581 return handle; 3582 } 3583 3584 On failure, `lt_dladvise_ext' returns non-zero and sets an error 3585 message that can be retrieved with `lt_dlerror'. 3586 3587 -- Function: int lt_dladvise_global (lt_dladvise *ADVISE) 3588 Set the `symglobal' hint on ADVISE. Passing an ADVISE parameter 3589 to `lt_dlopenadvise' with this hint set causes it to try to make 3590 the loaded module's symbols globally available for resolving 3591 unresolved symbols in subsequently loaded modules. 3592 3593 If neither the `symglobal' nor the `symlocal' hints are set, or if 3594 a module is loaded without using the `lt_dlopenadvise' call in any 3595 case, then the visibility of the module's symbols will be as per 3596 the default for the underlying module loader and OS. Even if a 3597 suitable hint is passed, not all loaders are able to act upon it in 3598 which case `lt_dlgetinfo' will reveal whether the hint was actually 3599 followed. 3600 3601 On failure, `lt_dladvise_global' returns non-zero and sets an error 3602 message that can be retrieved with `lt_dlerror'. 3603 3604 -- Function: int lt_dladvise_local (lt_dladvise *ADVISE) 3605 Set the `symlocal' hint on ADVISE. Passing an ADVISE parameter to 3606 `lt_dlopenadvise' with this hint set causes it to try to keep the 3607 loaded module's symbols hidden so that they are not visible to 3608 subsequently loaded modules. 3609 3610 If neither the `symglobal' nor the `symlocal' hints are set, or if 3611 a module is loaded without using the `lt_dlopenadvise' call in any 3612 case, then the visibility of the module's symbols will be as per 3613 the default for the underlying module loader and OS. Even if a 3614 suitable hint is passed, not all loaders are able to act upon it in 3615 which case `lt_dlgetinfo' will reveal whether the hint was actually 3616 followed. 3617 3618 On failure, `lt_dladvise_local' returns non-zero and sets an error 3619 message that can be retrieved with `lt_dlerror'. 3620 3621 -- Function: int lt_dladvise_resident (lt_dladvise *ADVISE) 3622 Set the `resident' hint on ADVISE. Passing an ADVISE parameter to 3623 `lt_dlopenadvise' with this hint set causes it to try to make the 3624 loaded module resident in memory, so that it cannot be unloaded 3625 with a later call to `lt_dlclose'. 3626 3627 On failure, `lt_dladvise_resident' returns non-zero and sets an 3628 error message that can be retrieved with `lt_dlerror'. 3629 3630 -- Function: int lt_dladvise_preload (lt_dladvise *ADVISE) 3631 Set the `preload' hint on ADVISE. Passing an ADVISE parameter to 3632 `lt_dlopenadvise' with this hint set causes it to load only 3633 preloaded modules, so that if a suitable preloaded module is not 3634 found, `lt_dlopenadvise' will return `NULL'. 3635 3636 -- Function: int lt_dlclose (lt_dlhandle HANDLE) 3637 Decrement the reference count on the module HANDLE. If it drops 3638 to zero and no other module depends on this module, then the 3639 module is unloaded. Return 0 on success. 3640 3641 -- Function: void * lt_dlsym (lt_dlhandle HANDLE, const char *NAME) 3642 Return the address in the module HANDLE, where the symbol given by 3643 the null-terminated string NAME is loaded. If the symbol cannot 3644 be found, `NULL' is returned. 3645 3646 -- Function: const char * lt_dlerror (void) 3647 Return a human readable string describing the most recent error 3648 that occurred from any of libltdl's functions. Return `NULL' if 3649 no errors have occurred since initialization or since it was last 3650 called. 3651 3652 -- Function: int lt_dladdsearchdir (const char *SEARCH_DIR) 3653 Append the search directory SEARCH_DIR to the current user-defined 3654 library search path. Return 0 on success. 3655 3656 -- Function: int lt_dlinsertsearchdir (const char *BEFORE, 3657 const char *SEARCH_DIR) 3658 Insert the search directory SEARCH_DIR into the user-defined 3659 library search path, immediately before the element starting at 3660 address BEFORE. If BEFORE is `NULL', then SEARCH_DIR is appending 3661 as if `lt_dladdsearchdir' had been called. Return 0 on success. 3662 3663 -- Function: int lt_dlsetsearchpath (const char *SEARCH_PATH) 3664 Replace the current user-defined library search path with 3665 SEARCH_PATH, which must be a list of absolute directories separated 3666 by `LT_PATHSEP_CHAR'. Return 0 on success. 3667 3668 -- Function: const char * lt_dlgetsearchpath (void) 3669 Return the current user-defined library search path. 3670 3671 -- Function: int lt_dlforeachfile (const char *SEARCH_PATH, 3672 int (*FUNC) (const char *FILENAME, void * DATA), void * DATA) 3673 In some applications you may not want to load individual modules 3674 with known names, but rather find all of the modules in a set of 3675 directories and load them all during initialisation. With this 3676 function you can have libltdl scan the `LT_PATHSEP_CHAR'-delimited 3677 directory list in SEARCH_PATH for candidates, and pass them, along 3678 with DATA to your own callback function, FUNC. If SEARCH_PATH is 3679 `NULL', then search all of the standard locations that `lt_dlopen' 3680 would examine. This function will continue to make calls to FUNC 3681 for each file that it discovers in SEARCH_PATH until one of these 3682 calls returns non-zero, or until the files are exhausted. 3683 `lt_dlforeachfile' returns the value returned by the last call 3684 made to FUNC. 3685 3686 For example you could define FUNC to build an ordered "argv"-like 3687 vector of files using DATA to hold the address of the start of the 3688 vector. 3689 3690 -- Function: int lt_dlmakeresident (lt_dlhandle HANDLE) 3691 Mark a module so that it cannot be `lt_dlclose'd. This can be 3692 useful if a module implements some core functionality in your 3693 project that would cause your code to crash if removed. Return 0 3694 on success. 3695 3696 If you use `lt_dlopen (NULL)' to get a HANDLE for the running 3697 binary, that handle will always be marked as resident, and 3698 consequently cannot be successfully `lt_dlclose'd. 3699 3700 -- Function: int lt_dlisresident (lt_dlhandle HANDLE) 3701 Check whether a particular module has been marked as resident, 3702 returning 1 if it has or 0 otherwise. If there is an error while 3703 executing this function, return -1 and set an error message for 3704 retrieval with `lt_dlerror'. 3705 3706 ---------- Footnotes ---------- 3707 3708 (1) Some platforms, notably Mac OS X, differentiate between a 3709runtime library that cannot be opened by `lt_dlopen' and a dynamic 3710module that can. For maximum portability you should try to ensure that 3711you only pass `lt_dlopen' objects that have been compiled with libtool's 3712`-module' flag. 3713 3714 3715File: libtool.info, Node: Modules for libltdl, Next: Thread Safety in libltdl, Prev: Libltdl interface, Up: Using libltdl 3716 371711.2 Creating modules that can be `dlopen'ed 3718============================================ 3719 3720Libtool modules are created like normal libtool libraries with a few 3721exceptions: 3722 3723 You have to link the module with libtool's `-module' switch, and you 3724should link any program that is intended to dlopen the module with 3725`-dlopen MODULENAME.LA' where possible, so that libtool can dlpreopen 3726the module on platforms that do not support dlopening. If the module 3727depends on any other libraries, make sure you specify them either when 3728you link the module or when you link programs that dlopen it. If you 3729want to disable versioning (*note Versioning::) for a specific module 3730you should link it with the `-avoid-version' switch. Note that libtool 3731modules don't need to have a "lib" prefix. However, Automake 1.4 or 3732higher is required to build such modules. 3733 3734 Usually a set of modules provide the same interface, i.e. exports 3735the same symbols, so that a program can dlopen them without having to 3736know more about their internals: In order to avoid symbol conflicts all 3737exported symbols must be prefixed with "modulename_LTX_" (MODULENAME is 3738the name of the module). Internal symbols must be named in such a way 3739that they won't conflict with other modules, for example, by prefixing 3740them with "_modulename_". Although some platforms support having the 3741same symbols defined more than once it is generally not portable and it 3742makes it impossible to dlpreopen such modules. 3743 3744 libltdl will automatically cut the prefix off to get the real name of 3745the symbol. Additionally, it supports modules that do not use a prefix 3746so that you can also dlopen non-libtool modules. 3747 3748 `foo1.c' gives an example of a portable libtool module. Exported 3749symbols are prefixed with "foo1_LTX_", internal symbols with "_foo1_". 3750Aliases are defined at the beginning so that the code is more readable. 3751 3752 /* aliases for the exported symbols */ 3753 #define foo foo1_LTX_foo 3754 #define bar foo1_LTX_bar 3755 3756 /* a global variable definition */ 3757 int bar = 1; 3758 3759 /* a private function */ 3760 int _foo1_helper() { 3761 return bar; 3762 } 3763 3764 /* an exported function */ 3765 int foo() { 3766 return _foo1_helper(); 3767 } 3768 3769The `Makefile.am' contains the necessary rules to build the module 3770`foo1.la': 3771 3772 ... 3773 lib_LTLIBRARIES = foo1.la 3774 3775 foo1_la_SOURCES = foo1.c 3776 foo1_la_LDFLAGS = -module 3777 ... 3778 3779 3780File: libtool.info, Node: Thread Safety in libltdl, Next: User defined module data, Prev: Modules for libltdl, Up: Using libltdl 3781 378211.3 Using libltdl in a multi threaded environment 3783================================================== 3784 3785Libltdl provides a wrapper around whatever dynamic run-time object 3786loading mechanisms are provided by the host system, many of which are 3787themselves not thread safe. Consequently libltdl cannot itself be 3788consistently thread safe. 3789 3790 If you wish to use libltdl in a multithreaded environment, then you 3791must mutex lock around libltdl calls, since they may in turn be calling 3792non-thread-safe system calls on some target hosts. 3793 3794 Some old releases of libtool provided a mutex locking API that was 3795unusable with POSIX threads, so callers were forced to lock around all 3796libltdl API calls anyway. That mutex locking API was next to useless, 3797and is not present in current releases. 3798 3799 Some future release of libtool may provide a new POSIX thread 3800compliant mutex locking API. 3801 3802 3803File: libtool.info, Node: User defined module data, Next: Module loaders for libltdl, Prev: Thread Safety in libltdl, Up: Using libltdl 3804 380511.4 Data associated with loaded modules 3806======================================== 3807 3808Some of the internal information about each loaded module that is 3809maintained by libltdl is available to the user, in the form of this 3810structure: 3811 3812 -- Type: struct lt_dlinfo { char *FILENAME; char *NAME; int REF_COUNT; 3813 int IS_RESIDENT; int IS_SYMGLOBAL; int IS_SYMLOCAL;} 3814 `lt_dlinfo' is used to store information about a module. The 3815 FILENAME attribute is a null-terminated character string of the 3816 real module file name. If the module is a libtool module then 3817 NAME is its module name (e.g. `"libfoo"' for `"dir/libfoo.la"'), 3818 otherwise it is set to `NULL'. The REF_COUNT attribute is a 3819 reference counter that describes how often the same module is 3820 currently loaded. The remaining fields can be compared to any 3821 hints that were passed to `lt_dlopenadvise' to determine whether 3822 the underlying loader was able to follow them. 3823 3824 The following function will return a pointer to libltdl's internal 3825copy of this structure for the given HANDLE: 3826 3827 -- Function: const lt_dlinfo * lt_dlgetinfo (lt_dlhandle HANDLE) 3828 Return a pointer to a struct that contains some information about 3829 the module HANDLE. The contents of the struct must not be 3830 modified. Return `NULL' on failure. 3831 3832 Furthermore, in order to save you from having to keep a list of the 3833handles of all the modules you have loaded, these functions allow you to 3834iterate over libltdl's list of loaded modules: 3835 3836 -- Type: lt_dlinterface_id 3837 The opaque type used to hold the module interface details for each 3838 registered libltdl client. 3839 3840 -- Type: int lt_dlhandle_interface (lt_dlhandle HANDLE, 3841 const char *ID_STRING) 3842 Functions of this type are called to check that a handle conforms 3843 to a library's expected module interface when iterating over the 3844 global handle list. You should be careful to write a callback 3845 function of this type that can correctly identify modules that 3846 belong to this client, both to prevent other clients from 3847 accidentally finding your loaded modules with the iterator 3848 functions below, and vice versa. The best way to do this is to 3849 check that module HANDLE conforms to the interface specification 3850 of your loader using `lt_dlsym'. 3851 3852 The callback may be given *every* module loaded by all the libltdl 3853 module clients in the current address space, including any modules 3854 loaded by other libraries such as libltdl itself, and should 3855 return non-zero if that module does not fulfill the interface 3856 requirements of your loader. 3857 3858 int 3859 my_interface_cb (lt_dlhandle handle, const char *id_string) 3860 { 3861 char *(*module_id) (void) = NULL; 3862 3863 /* A valid my_module must provide all of these symbols. */ 3864 if (!((module_id = (char*(*)(void)) lt_dlsym ("module_version")) 3865 && lt_dlsym ("my_module_entrypoint"))) 3866 return 1; 3867 3868 if (strcmp (id_string, module_id()) != 0) 3869 return 1; 3870 3871 return 0; 3872 } 3873 3874 -- Function: lt_dlinterface_id lt_dlinterface_register 3875 (const char *ID_STRING, lt_dlhandle_interface *IFACE) 3876 Use this function to register your interface validator with 3877 libltdl, and in return obtain a unique key to store and retrieve 3878 per-module data. You supply an ID_STRING and IFACE so that the 3879 resulting `lt_dlinterface_id' can be used to filter the module 3880 handles returned by the iteration functions below. If IFACE is 3881 `NULL', all modules will be matched. 3882 3883 -- Function: void lt_dlinterface_free (lt_dlinterface_id IFACE) 3884 Release the data associated with IFACE. 3885 3886 -- Function: int lt_dlhandle_map (lt_dlinterface_id IFACE, 3887 int (*FUNC) (lt_dlhandle HANDLE, void * DATA), void * DATA) 3888 For each module that matches IFACE, call the function FUNC. When 3889 writing the FUNC callback function, the argument HANDLE is the 3890 handle of a loaded module, and DATA is the last argument passed to 3891 `lt_dlhandle_map'. As soon as FUNC returns a non-zero value for 3892 one of the handles, `lt_dlhandle_map' will stop calling FUNC and 3893 immediately return that non-zero value. Otherwise 0 is eventually 3894 returned when FUNC has been successfully called for all matching 3895 modules. 3896 3897 -- Function: lt_dlhandle lt_dlhandle_iterate (lt_dlinterface_id IFACE, 3898 lt_dlhandle PLACE) 3899 Iterate over the module handles loaded by IFACE, returning the 3900 first matching handle in the list if PLACE is `NULL', and the next 3901 one on subsequent calls. If PLACE is the last element in the list 3902 of eligible modules, this function returns `NULL'. 3903 3904 lt_dlhandle handle = 0; 3905 lt_dlinterface_id iface = my_interface_id; 3906 3907 while ((handle = lt_dlhandle_iterate (iface, handle))) 3908 { 3909 ... 3910 } 3911 3912 -- Function: lt_dlhandle lt_dlhandle_fetch (lt_dlinterface_id IFACE, 3913 const char *MODULE_NAME) 3914 Search through the module handles loaded by IFACE for a module 3915 named MODULE_NAME, returning its handle if found or else `NULL' if 3916 no such named module has been loaded by IFACE. 3917 3918 However, you might still need to maintain your own list of loaded 3919module handles (in parallel with the list maintained inside libltdl) if 3920there were any other data that your application wanted to associate 3921with each open module. Instead, you can use the following API calls to 3922do that for you. You must first obtain a unique interface id from 3923libltdl as described above, and subsequently always use it to retrieve 3924the data you stored earlier. This allows different libraries to each 3925store their own data against loaded modules, without interfering with 3926one another. 3927 3928 -- Function: void * lt_dlcaller_set_data (lt_dlinterface_id KEY, 3929 lt_dlhandle HANDLE, void * DATA) 3930 Set DATA as the set of data uniquely associated with KEY and 3931 HANDLE for later retrieval. This function returns the DATA 3932 previously associated with KEY and HANDLE if any. A result of 0, 3933 may indicate that a diagnostic for the last error (if any) is 3934 available from `lt_dlerror()'. 3935 3936 For example, to correctly remove some associated data: 3937 3938 void *stale = lt_dlcaller_set_data (key, handle, 0); 3939 if (stale != NULL) 3940 { 3941 free (stale); 3942 } 3943 else 3944 { 3945 char *error_msg = lt_dlerror (); 3946 3947 if (error_msg != NULL) 3948 { 3949 my_error_handler (error_msg); 3950 return STATUS_FAILED; 3951 } 3952 } 3953 3954 -- Function: void * lt_dlcaller_get_data (lt_dlinterface_id KEY, 3955 lt_dlhandle HANDLE) 3956 Return the address of the data associated with KEY and HANDLE, or 3957 else `NULL' if there is none. 3958 3959 Old versions of libltdl also provided a simpler, but similar, API 3960based around `lt_dlcaller_id'. Unfortunately, it had no provision for 3961detecting whether a module belonged to a particular interface as 3962libltdl didn't support multiple loaders in the same address space at 3963that time. Those APIs are no longer supported as there would be no way 3964to stop clients of the old APIs from seeing (and accidentally altering) 3965modules loaded by other libraries. 3966 3967 3968File: libtool.info, Node: Module loaders for libltdl, Next: Distributing libltdl, Prev: User defined module data, Up: Using libltdl 3969 397011.5 How to create and register new module loaders 3971================================================== 3972 3973Sometimes libltdl's many ways of gaining access to modules are not 3974sufficient for the purposes of a project. You can write your own 3975loader, and register it with libltdl so that `lt_dlopen' will be able 3976to use it. 3977 3978 Writing a loader involves writing at least three functions that can 3979be called by `lt_dlopen', `lt_dlsym' and `lt_dlclose'. Optionally, you 3980can provide a finalisation function to perform any cleanup operations 3981when `lt_dlexit' executes, and a symbol prefix string that will be 3982prepended to any symbols passed to `lt_dlsym'. These functions must 3983match the function pointer types below, after which they can be 3984allocated to an instance of `lt_user_dlloader' and registered. 3985 3986 Registering the loader requires that you choose a name for it, so 3987that it can be recognised by `lt_dlloader_find' and removed with 3988`lt_dlloader_remove'. The name you choose must be unique, and not 3989already in use by libltdl's builtin loaders: 3990 3991"dlopen" 3992 The system dynamic library loader, if one exists. 3993 3994"dld" 3995 The GNU dld loader, if `libdld' was installed when libltdl was 3996 built. 3997 3998"dlpreload" 3999 The loader for `lt_dlopen'ing of preloaded static modules. 4000 4001 The prefix "dl" is reserved for loaders supplied with future 4002versions of libltdl, so you should not use that for your own loader 4003names. 4004 4005The following types are defined in `ltdl.h': 4006 4007 -- Type: lt_module 4008 `lt_module' is a dlloader dependent module. The dynamic module 4009 loader extensions communicate using these low level types. 4010 4011 -- Type: lt_dlloader 4012 `lt_dlloader' is a handle for module loader types. 4013 4014 -- Type: lt_user_data 4015 `lt_user_data' is used for specifying loader instance data. 4016 4017 -- Type: struct lt_user_dlloader {const char *SYM_PREFIX; 4018 lt_module_open *MODULE_OPEN; lt_module_close *MODULE_CLOSE; 4019 lt_find_sym *FIND_SYM; lt_dlloader_exit *DLLOADER_EXIT; } 4020 If you want to define a new way to open dynamic modules, and have 4021 the `lt_dlopen' API use it, you need to instantiate one of these 4022 structures and pass it to `lt_dlloader_add'. You can pass whatever 4023 you like in the DLLOADER_DATA field, and it will be passed back as 4024 the value of the first parameter to each of the functions 4025 specified in the function pointer fields. 4026 4027 -- Type: lt_module lt_module_open (const char *FILENAME) 4028 The type of the loader function for an `lt_dlloader' module 4029 loader. The value set in the dlloader_data field of the `struct 4030 lt_user_dlloader' structure will be passed into this function in 4031 the LOADER_DATA parameter. Implementation of such a function 4032 should attempt to load the named module, and return an `lt_module' 4033 suitable for passing in to the associated `lt_module_close' and 4034 `lt_sym_find' function pointers. If the function fails it should 4035 return `NULL', and set the error message with `lt_dlseterror'. 4036 4037 -- Type: int lt_module_close (lt_user_data LOADER_DATA, 4038 lt_module MODULE) 4039 The type of the unloader function for a user defined module loader. 4040 Implementation of such a function should attempt to release any 4041 resources tied up by the MODULE module, and then unload it from 4042 memory. If the function fails for some reason, set the error 4043 message with `lt_dlseterror' and return non-zero. 4044 4045 -- Type: void * lt_find_sym (lt_module MODULE, const char *SYMBOL) 4046 The type of the symbol lookup function for a user defined module 4047 loader. Implementation of such a function should return the 4048 address of the named SYMBOL in the module MODULE, or else set the 4049 error message with `lt_dlseterror' and return `NULL' if lookup 4050 fails. 4051 4052 -- Type: int lt_dlloader_exit (lt_user_data LOADER_DATA) 4053 The type of the finalisation function for a user defined module 4054 loader. Implementation of such a function should free any 4055 resources associated with the loader, including any user specified 4056 data in the `dlloader_data' field of the `lt_user_dlloader'. If 4057 non-`NULL', the function will be called by `lt_dlexit', and 4058 `lt_dlloader_remove'. 4059 4060 For example: 4061 4062 int 4063 register_myloader (void) 4064 { 4065 lt_user_dlloader dlloader; 4066 4067 /* User modules are responsible for their own initialisation. */ 4068 if (myloader_init () != 0) 4069 return MYLOADER_INIT_ERROR; 4070 4071 dlloader.sym_prefix = NULL; 4072 dlloader.module_open = myloader_open; 4073 dlloader.module_close = myloader_close; 4074 dlloader.find_sym = myloader_find_sym; 4075 dlloader.dlloader_exit = myloader_exit; 4076 dlloader.dlloader_data = (lt_user_data)myloader_function; 4077 4078 /* Add my loader as the default module loader. */ 4079 if (lt_dlloader_add (lt_dlloader_next (NULL), &dlloader, "myloader") != 0) 4080 return ERROR; 4081 4082 return OK; 4083 } 4084 4085 Note that if there is any initialisation required for the loader, it 4086must be performed manually before the loader is registered - libltdl 4087doesn't handle user loader initialisation. 4088 4089 Finalisation _is_ handled by libltdl however, and it is important to 4090ensure the `dlloader_exit' callback releases any resources claimed 4091during the initialisation phase. 4092 4093libltdl provides the following functions for writing your own module 4094loaders: 4095 4096 -- Function: int lt_dlloader_add (lt_dlloader *PLACE, 4097 lt_user_dlloader *DLLOADER, const char *LOADER_NAME) 4098 Add a new module loader to the list of all loaders, either as the 4099 last loader (if PLACE is `NULL'), else immediately before the 4100 loader passed as PLACE. LOADER_NAME will be returned by 4101 `lt_dlloader_name' if it is subsequently passed a newly registered 4102 loader. These LOADER_NAMEs must be unique, or 4103 `lt_dlloader_remove' and `lt_dlloader_find' cannot work. Returns 4104 0 for success. 4105 4106 /* Make myloader be the last one. */ 4107 if (lt_dlloader_add (NULL, myloader) != 0) 4108 perror (lt_dlerror ()); 4109 4110 -- Function: int lt_dlloader_remove (const char *LOADER_NAME) 4111 Remove the loader identified by the unique name, LOADER_NAME. 4112 Before this can succeed, all modules opened by the named loader 4113 must have been closed. Returns 0 for success, otherwise an error 4114 message can be obtained from `lt_dlerror'. 4115 4116 /* Remove myloader. */ 4117 if (lt_dlloader_remove ("myloader") != 0) 4118 perror (lt_dlerror ()); 4119 4120 -- Function: lt_dlloader * lt_dlloader_next (lt_dlloader *PLACE) 4121 Iterate over the module loaders, returning the first loader if 4122 PLACE is `NULL', and the next one on subsequent calls. The handle 4123 is for use with `lt_dlloader_add'. 4124 4125 /* Make myloader be the first one. */ 4126 if (lt_dlloader_add (lt_dlloader_next (NULL), myloader) != 0) 4127 return ERROR; 4128 4129 -- Function: lt_dlloader * lt_dlloader_find (const char *LOADER_NAME) 4130 Return the first loader with a matching LOADER_NAME identifier, or 4131 else `NULL', if the identifier is not found. 4132 4133 The identifiers that may be used by libltdl itself, if the host 4134 architecture supports them are "dlopen"(1), "dld" and "dlpreload". 4135 4136 /* Add a user loader as the next module loader to be tried if 4137 the standard dlopen loader were to fail when lt_dlopening. */ 4138 if (lt_dlloader_add (lt_dlloader_find ("dlopen"), myloader) != 0) 4139 return ERROR; 4140 4141 -- Function: const char * lt_dlloader_name (lt_dlloader *PLACE) 4142 Return the identifying name of PLACE, as obtained from 4143 `lt_dlloader_next' or `lt_dlloader_find'. If this function fails, 4144 it will return `NULL' and set an error for retrieval with 4145 `lt_dlerror'. 4146 4147 -- Function: lt_user_data * lt_dlloader_data (lt_dlloader *PLACE) 4148 Return the address of the `dlloader_data' of PLACE, as obtained 4149 from `lt_dlloader_next' or `lt_dlloader_find'. If this function 4150 fails, it will return `NULL' and set an error for retrieval with 4151 `lt_dlerror'. 4152 415311.5.1 Error handling within user module loaders 4154------------------------------------------------ 4155 4156 -- Function: int lt_dladderror (const char *DIAGNOSTIC) 4157 This function allows you to integrate your own error messages into 4158 `lt_dlerror'. Pass in a suitable diagnostic message for return by 4159 `lt_dlerror', and an error identifier for use with `lt_dlseterror' 4160 is returned. 4161 4162 If the allocation of an identifier fails, this function returns -1. 4163 4164 int myerror = lt_dladderror ("Doh!"); 4165 if (myerror < 0) 4166 perror (lt_dlerror ()); 4167 4168 -- Function: int lt_dlseterror (int ERRORCODE) 4169 When writing your own module loaders, you should use this function 4170 to raise errors so that they are propagated through the 4171 `lt_dlerror' interface. All of the standard errors used by 4172 libltdl are declared in `ltdl.h', or you can add more of your own 4173 with `lt_dladderror'. This function returns 0 on success. 4174 4175 if (lt_dlseterror (LTDL_ERROR_NO_MEMORY) != 0) 4176 perror (lt_dlerror ()); 4177 4178---------- Footnotes ---------- 4179 4180 (1) This is used for the host dependent module loading API - 4181`shl_load' and `LoadLibrary' for example 4182 4183 4184File: libtool.info, Node: Distributing libltdl, Prev: Module loaders for libltdl, Up: Using libltdl 4185 418611.6 How to distribute libltdl with your package 4187================================================ 4188 4189Even though libltdl is installed together with libtool, you may wish to 4190include libltdl in the distribution of your package, for the 4191convenience of users of your package that don't have libtool or libltdl 4192installed, or if you are using features of a very new version of 4193libltdl that you don't expect your users to have yet. In such cases, 4194you must decide which flavor of libltdl you want to use: a convenience 4195library or an installable libtool library. 4196 4197 The most simplistic way to add `libltdl' to your package is to copy 4198all the `libltdl' source files to a subdirectory within your package 4199and to build and link them along with the rest of your sources. To 4200help you do this, the m4 macros for Autoconf are available in 4201`ltdl.m4'. You must ensure that they are available in `aclocal.m4' 4202before you run Autoconf(1). Having made the macros available, you must 4203add a call to the `LTDL_INIT' macro (after the call to `LT_INIT') to 4204your package's `configure.ac' to perform the configure time checks 4205required to build the library correctly. Unfortunately, this method 4206has problems if you then try to link the package binaries with an 4207installed libltdl, or a library that depends on libltdl, because of the 4208duplicate symbol definitions. For example, ultimately linking against 4209two different versions of libltdl, or against both a local convenience 4210library and an installed libltdl is bad. Ensuring that only one copy 4211of the libltdl sources are linked into any program is left as an 4212exercise for the reader. 4213 4214 -- Macro: LT_CONFIG_LTDL_DIR (DIRECTORY) 4215 Declare DIRECTORY to be the location of the `libltdl' source 4216 files, for `libtoolize --ltdl' to place them. *Note Invoking 4217 libtoolize::, for more details. Provided that you add an 4218 appropriate `LT_CONFIG_LTDL_DIR' call in your `configure.ac' 4219 before calling `libtoolize', the appropriate `libltdl' files will 4220 be installed automatically. 4221 4222 -- Macro: LTDL_INIT (OPTIONS) 4223 -- Macro: LT_WITH_LTDL 4224 -- Macro: AC_WITH_LTDL 4225 `AC_WITH_LTDL' and `LT_WITH_LTDL' are deprecated names for older 4226 versions of this macro; `autoupdate' will update your 4227 `configure.ac' file. 4228 4229 This macro adds the following options to the `configure' script: 4230 4231 `--with-ltdl-include INSTALLED-LTDL-HEADER-DIR' 4232 The `LTDL_INIT' macro will look in the standard header file 4233 locations to find the installed `libltdl' headers. If 4234 `LTDL_INIT' can't find them by itself, the person who builds 4235 your package can use this option to tell `configure' where 4236 the installed `libltdl' headers are. 4237 4238 `--with-ltdl-lib INSTALLED-LTDL-LIBRARY-DIR' 4239 Similarly, the person building your package can use this 4240 option to help `configure' find the installed `libltdl.la'. 4241 4242 `--with-included-ltdl' 4243 If there is no installed `libltdl', or in any case if the 4244 person building your package would rather use the `libltdl' 4245 sources shipped with the package in the subdirectory named by 4246 `LT_CONFIG_LTDL_DIR', they should pass this option to 4247 `configure'. 4248 4249 If the `--with-included-ltdl' is not passed at configure time, and 4250 an installed `libltdl' is not found(2), then `configure' will exit 4251 immediately with an error that asks the user to either specify the 4252 location of an installed `libltdl' using the `--with-ltdl-include' 4253 and `--with-ltdl-lib' options, or to build with the `libltdl' 4254 sources shipped with the package by passing `--with-included-ltdl'. 4255 4256 If an installed `libltdl' is found, then `LIBLTDL' is set to the 4257 link flags needed to use it, and `LTDLINCL' to the preprocessor 4258 flags needed to find the installed headers, and `LTDLDEPS' will be 4259 empty. Note, however, that no version checking is performed. You 4260 should manually check for the `libltdl' features you need in 4261 `configure.ac': 4262 4263 LT_INIT([dlopen]) 4264 LTDL_INIT 4265 4266 # The lt_dladvise_init symbol was added with libtool-2.2 4267 if test "x$with_included_ltdl" != "xyes"; then 4268 save_CFLAGS="$CFLAGS" 4269 save_LDFLAGS="$LDFLAGS" 4270 CFLAGS="$CFLAGS $LTDLINCL" 4271 LDFLAGS="$LDFLAGS $LIBLTDL" 4272 AC_CHECK_LIB([ltdl], [lt_dladvise_init], 4273 [], 4274 [AC_MSG_ERROR([installed libltdl is too old])]) 4275 LDFLAGS="$save_LDFLAGS" 4276 CFLAGS="$save_CFLAGS" 4277 fi 4278 4279 OPTIONS may include no more than one of the following build modes 4280 depending on how you want your project to build `libltdl': 4281 `nonrecursive', `recursive', or `subproject'. In order for 4282 `libtoolize' to detect this option correctly, if you supply one of 4283 these arguments, they must be given literally (i.e., macros or 4284 shell variables that expand to the correct ltdl mode will not 4285 work). 4286 4287 `nonrecursive' 4288 This is how the Libtool project distribution builds the 4289 `libltdl' we ship and install. If you wish to use Automake 4290 to build `libltdl' without invoking a recursive make to 4291 descend into the `libltdl' subdirectory, then use this 4292 option. You will need to set your configuration up carefully 4293 to make this work properly, and you will need releases of 4294 Autoconf and Automake that support `subdir-objects' and 4295 `LIBOBJDIR' properly. In your `configure.ac', add: 4296 4297 AM_INIT_AUTOMAKE([subdir-objects]) 4298 AC_CONFIG_HEADERS([config.h]) 4299 LT_CONFIG_LTDL_DIR([libltdl]) 4300 LT_INIT([dlopen]) 4301 LTDL_INIT([nonrecursive]) 4302 4303 You _have to_ use a config header, but it may have a name 4304 different than `config.h'. 4305 4306 Also, add the following near the top of your `Makefile.am': 4307 4308 AM_CPPFLAGS = 4309 AM_LDFLAGS = 4310 4311 BUILT_SOURCES = 4312 EXTRA_DIST = 4313 CLEANFILES = 4314 MOSTLYCLEANFILES = 4315 4316 include_HEADERS = 4317 noinst_LTLIBRARIES = 4318 lib_LTLIBRARIES = 4319 EXTRA_LTLIBRARIES = 4320 4321 include libltdl/Makefile.inc 4322 4323 Unless you build no other libraries from this `Makefile.am', 4324 you will also need to change `lib_LTLIBRARIES' to assign with 4325 `+=' so that the `libltdl' targets declared in `Makefile.inc' 4326 are not overwritten. 4327 4328 `recursive' 4329 This build mode still requires that you use Automake, but (in 4330 contrast with `nonrecursive') uses the more usual device of 4331 starting another `make' process in the `libltdl' 4332 subdirectory. To use this mode, you should add to your 4333 `configure.ac': 4334 4335 AM_INIT_AUTOMAKE 4336 AC_CONFIG_HEADERS([config.h]) 4337 LT_CONFIG_LTDL_DIR([libltdl]) 4338 LT_INIT([dlopen]) 4339 LTDL_INIT([recursive]) 4340 AC_CONFIG_FILES([libltdl/Makefile]) 4341 4342 Again, you _have to_ use a config header, but it may have a 4343 name different than `config.h' if you like. 4344 4345 Also, add this to your `Makefile.am': 4346 4347 SUBDIRS = libltdl 4348 4349 `subproject' 4350 This mode is the default unless you explicitly add 4351 `recursive' or `nonrecursive' to your `LTDL_INIT' options; 4352 `subproject' is the only mode supported by previous releases 4353 of libltdl. Even if you do not use Autoconf in the parent 4354 project, then, in `subproject' mode, still `libltdl' contains 4355 all the necessary files to configure and build itself - you 4356 just need to arrange for your build system to call 4357 `libltdl/configure' with appropriate options, and then run 4358 `make' in the `libltdl' subdirectory. 4359 4360 If you _are_ using Autoconf and Automake, then you will need 4361 to add the following to your `configure.ac': 4362 4363 LT_CONFIG_LTDL_DIR([libltdl]) 4364 LTDL_INIT 4365 4366 and to `Makefile.am': 4367 4368 SUBDIRS = libltdl 4369 4370 Aside from setting the libltdl build mode, there are other keywords 4371 that you can pass to `LTDL_INIT' to modify its behavior when 4372 `--with-included-ltdl' has been given: 4373 4374 `convenience' 4375 This is the default unless you explicitly add `installable' to 4376 your `LTDL_INIT' options. 4377 4378 This keyword will cause options to be passed to the 4379 `configure' script in the subdirectory named by 4380 `LT_CONFIG_LTDL_DIR' in order to cause it to be built as a 4381 convenience library. If you're not using automake, you will 4382 need to define `top_build_prefix', `top_builddir', and 4383 `top_srcdir' in your makefile so that `LIBLTDL', `LTDLDEPS', 4384 and `LTDLINCL' expand correctly. 4385 4386 One advantage of the convenience library is that it is not 4387 installed, so the fact that you use `libltdl' will not be 4388 apparent to the user, and it won't overwrite a pre-installed 4389 version of `libltdl' the system might already have in the 4390 installation directory. On the other hand, if you want to 4391 upgrade `libltdl' for any reason (e.g. a bugfix) you'll have 4392 to recompile your package instead of just replacing the 4393 shared installed version of `libltdl'. However, if your 4394 programs or libraries are linked with other libraries that 4395 use such a pre-installed version of `libltdl', you may get 4396 linker errors or run-time crashes. Another problem is that 4397 you cannot link the convenience library into more than one 4398 libtool library, then link a single program with those 4399 libraries, because you may get duplicate symbols. In general 4400 you can safely use the convenience library in programs that 4401 don't depend on other libraries that might use `libltdl' too. 4402 4403 `installable' 4404 This keyword will pass options to the `configure' script in 4405 the subdirectory named by `LT_CONFIG_LTDL_DIR' in order to 4406 cause it to be built as an installable library. If you're not 4407 using automake, you will need to define `top_build_prefix', 4408 `top_builddir' and `top_srcdir' in your makefile so that 4409 `LIBLTDL', `LTDLDEPS', and `LTDLINCL' are expanded properly. 4410 4411 Be aware that you could overwrite another `libltdl' already 4412 installed to the same directory if you use this option. 4413 4414 Whatever method you use, `LTDL_INIT' will define the shell variable 4415LIBLTDL to the link flag that you should use to link with `libltdl', 4416the shell variable LTDLDEPS to the files that can be used as a 4417dependency in `Makefile' rules, and the shell variable LTDLINCL to the 4418preprocessor flag that you should use to compile programs that include 4419`ltdl.h'. So, when you want to link a program with libltdl, be it a 4420convenience, installed or installable library, just use `$(LTDLINCL)' 4421for preprocessing and compilation, and `$(LIBLTDL)' for linking. 4422 4423 * If your package is built using an installed version of `libltdl', 4424 LIBLTDL will be set to the compiler flags needed to link against 4425 the installed library, LTDLDEPS will be empty, and LTDLINCL will 4426 be set to the compiler flags needed to find the `libltdl' header 4427 files. 4428 4429 * If your package is built using the convenience libltdl, LIBLTDL 4430 and LTDLDEPS will be the pathname for the convenience version of 4431 libltdl (starting with `${top_builddir}/' or 4432 `${top_build_prefix}') and LTDLINCL will be `-I' followed by the 4433 directory that contains `ltdl.h' (starting with `${top_srcdir}/'). 4434 4435 * If an installable version of the included `libltdl' is being 4436 built, its pathname starting with `${top_builddir}/' or 4437 `${top_build_prefix}', will be stored in LIBLTDL and LTDLDEPS, and 4438 LTDLINCL will be set just like in the case of convenience library. 4439 4440 You should probably also use the `dlopen' option to `LT_INIT' in 4441your `configure.ac', otherwise libtool will assume no dlopening 4442mechanism is supported, and revert to dlpreopening, which is probably 4443not what you want. Avoid using the `-static', `-static-libtool-libs', 4444or `-all-static' switches when linking programs with libltdl. This 4445will not work on all platforms, because the dlopening functions may not 4446be available for static linking. 4447 4448 The following example shows you how to embed an installable libltdl 4449in your package. In order to use the convenience variant, just replace 4450the `LTDL_INIT' option `installable' with `convenience'. We assume 4451that libltdl was embedded using `libtoolize --ltdl'. 4452 4453 configure.ac: 4454 ... 4455 # Name the subdirectory that contains libltdl sources 4456 LT_CONFIG_LTDL_DIR([libltdl]) 4457 4458 # Configure libtool with dlopen support if possible 4459 LT_INIT([dlopen]) 4460 4461 # Enable building of the installable libltdl library 4462 LTDL_INIT([installable]) 4463 ... 4464 4465 Makefile.am: 4466 ... 4467 SUBDIRS = libltdl 4468 4469 AM_CPPFLAGS = $(LTDLINCL) 4470 4471 myprog_LDFLAGS = -export-dynamic 4472 myprog_LDADD = $(LIBLTDL) -dlopen self -dlopen foo1.la 4473 myprog_DEPENDENCIES = $(LTDLDEPS) foo1.la 4474 ... 4475 4476 -- Macro: LTDL_INSTALLABLE 4477 -- Macro: AC_LIBLTDL_INSTALLABLE 4478 These macros are deprecated, the `installable' option to 4479 `LTDL_INIT' should be used instead. 4480 4481 -- Macro: LTDL_CONVENIENCE 4482 -- Macro: AC_LIBLTDL_CONVENIENCE 4483 These macros are deprecated, the `convenience' option to 4484 `LTDL_INIT' should be used instead. 4485 4486 ---------- Footnotes ---------- 4487 4488 (1) We used to recommend adding the contents of `ltdl.m4' to 4489`acinclude.m4', but with `aclocal' from a modern Automake (1.8 or 4490newer) and this release of libltdl that is not only unnecessary but 4491makes it easy to forget to upgrade `acinclude.m4' if you move to a 4492different release of libltdl. 4493 4494 (2) Even if libltdl is installed, `LTDL_INIT' may fail to detect it 4495if libltdl depends on symbols provided by libraries other than the C 4496library. 4497 4498 4499File: libtool.info, Node: Trace interface, Next: FAQ, Prev: Using libltdl, Up: Top 4500 450112 Libtool's trace interface 4502**************************** 4503 4504This section describes macros whose sole purpose is to be traced using 4505Autoconf's `--trace' option (*note The Autoconf Manual: 4506(autoconf)autoconf Invocation.) to query the Libtool configuration of a 4507project. These macros are called by Libtool internals and should never 4508be called by user code; they should only be traced. 4509 4510 -- Macro: LT_SUPPORTED_TAG (TAG) 4511 This macro is called once for each language enabled in the 4512 package. Its only argument, TAG, is the tag-name corresponding to 4513 the language (*note Tags::). 4514 4515 You can therefore retrieve the list of all tags enabled in a 4516 project using the following command: 4517 autoconf --trace 'LT_SUPPORTED_TAG:$1' 4518 4519 4520File: libtool.info, Node: FAQ, Next: Troubleshooting, Prev: Trace interface, Up: Top 4521 452213 Frequently Asked Questions about libtool 4523******************************************* 4524 4525This chapter covers some questions that often come up on the mailing 4526lists. 4527 4528* Menu: 4529 4530* Stripped link flags:: Dropped flags when creating a library 4531 4532 4533File: libtool.info, Node: Stripped link flags, Up: FAQ 4534 453513.1 Why does libtool strip link flags when creating a library? 4536=============================================================== 4537 4538When creating a shared library, but not when compiling or creating a 4539program, `libtool' drops some flags from the command line provided by 4540the user. This is done because flags unknown to `libtool' may 4541interfere with library creation or require additional support from 4542`libtool', and because omitting flags is usually the conservative 4543choice for a successful build. 4544 4545 If you encounter flags that you think are useful to pass, as a 4546work-around you can prepend flags with `-Wc,' or `-Xcompiler ' to allow 4547them to be passed through to the compiler driver (*note Link mode::). 4548Another possibility is to add flags already to the compiler command at 4549`configure' run time: 4550 4551 ./configure CC='gcc -m64' 4552 4553 If you think `libtool' should let some flag through by default, 4554here's how you can test such an inclusion: grab the Libtool development 4555tree, edit the `ltmain.m4sh' file in the `libltdl/config' subdirectory 4556to pass through the flag (search for `Flags to be passed through'), 4557re-bootstrap and build with the flags in question added to `LDFLAGS', 4558`CFLAGS', `CXXFLAGS', etc. on the `configure' command line as 4559appropriate. Run the testsuite as described in the `README' file and 4560report results to the Libtool bug reporting address 4561<bug-libtool@gnu.org>. 4562 4563 4564File: libtool.info, Node: Troubleshooting, Next: Maintaining, Prev: FAQ, Up: Top 4565 456614 Troubleshooting 4567****************** 4568 4569Libtool is under constant development, changing to remain up-to-date 4570with modern operating systems. If libtool doesn't work the way you 4571think it should on your platform, you should read this chapter to help 4572determine what the problem is, and how to resolve it. 4573 4574* Menu: 4575 4576* Libtool test suite:: Libtool's self-tests. 4577* Reporting bugs:: How to report problems with libtool. 4578 4579 4580File: libtool.info, Node: Libtool test suite, Next: Reporting bugs, Up: Troubleshooting 4581 458214.1 The libtool test suite 4583=========================== 4584 4585Libtool comes with two integrated sets of tests to check that your build 4586is sane, that test its capabilities, and report obvious bugs in the 4587libtool program. These tests, too, are constantly evolving, based on 4588past problems with libtool, and known deficiencies in other operating 4589systems. 4590 4591 As described in the `README' file, you may run `make -k check' after 4592you have built libtool (possibly before you install it) in order to 4593make sure that it meets basic functional requirements. 4594 4595* Menu: 4596 4597* Test descriptions:: The contents of the old test suite. 4598* When tests fail:: What to do when a test fails. 4599 4600 4601File: libtool.info, Node: Test descriptions, Next: When tests fail, Up: Libtool test suite 4602 460314.1.1 Description of test suite 4604-------------------------------- 4605 4606Here is a list of the current programs in the old test suite, and what 4607they test for: 4608 4609`cdemo-conf.test' 4610`cdemo-exec.test' 4611`cdemo-make.test' 4612`cdemo-static.test' 4613`cdemo-shared.test' 4614`cdemo-undef.test' 4615 These programs check to see that the `tests/cdemo' subdirectory of 4616 the libtool distribution can be configured and built correctly. 4617 4618 The `tests/cdemo' subdirectory contains a demonstration of libtool 4619 convenience libraries, a mechanism that allows build-time static 4620 libraries to be created, in a way that their components can be 4621 later linked into programs or other libraries, even shared ones. 4622 4623 The tests `cdemo-make.test' and `cdemo-exec.test' are executed 4624 three times, under three different libtool configurations: 4625 `cdemo-conf.test' configures `cdemo/libtool' to build both static 4626 and shared libraries (the default for platforms that support 4627 both), `cdemo-static.test' builds only static libraries 4628 (`--disable-shared'), and `cdemo-shared.test' builds only shared 4629 libraries (`--disable-static'). 4630 4631 The test `cdemo-undef.test' tests the generation of shared 4632 libraries with undefined symbols on systems that allow this. 4633 4634`demo-conf.test' 4635`demo-exec.test' 4636`demo-inst.test' 4637`demo-make.test' 4638`demo-unst.test' 4639`demo-static.test' 4640`demo-shared.test' 4641`demo-nofast.test' 4642`demo-pic.test' 4643`demo-nopic.test' 4644 These programs check to see that the `tests/demo' subdirectory of 4645 the libtool distribution can be configured, built, installed, and 4646 uninstalled correctly. 4647 4648 The `tests/demo' subdirectory contains a demonstration of a trivial 4649 package that uses libtool. The tests `demo-make.test', 4650 `demo-exec.test', `demo-inst.test' and `demo-unst.test' are 4651 executed four times, under four different libtool configurations: 4652 `demo-conf.test' configures `demo/libtool' to build both static 4653 and shared libraries, `demo-static.test' builds only static 4654 libraries (`--disable-shared'), and `demo-shared.test' builds only 4655 shared libraries (`--disable-static'). `demo-nofast.test' 4656 configures `demo/libtool' to disable the fast-install mode 4657 (`--enable-fast-install=no'). `demo-pic.test' configures 4658 `demo/libtool' to prefer building PIC code (`--with-pic'), 4659 `demo-nopic.test' to prefer non-PIC code (`--without-pic'). 4660 4661`demo-deplibs.test' 4662 Many systems cannot link static libraries into shared libraries. 4663 libtool uses a `deplibs_check_method' to prevent such cases. This 4664 tests checks whether libtool's `deplibs_check_method' works 4665 properly. 4666 4667`demo-hardcode.test' 4668 On all systems with shared libraries, the location of the library 4669 can be encoded in executables that are linked against it *note 4670 Linking executables::. This test checks the conditions under 4671 which your system linker hardcodes the library location, and 4672 guarantees that they correspond to libtool's own notion of how 4673 your linker behaves. 4674 4675`demo-relink.test' 4676`depdemo-relink.test' 4677 These tests check whether variable SHLIBPATH_OVERRIDES_RUNPATH is 4678 properly set. If the test fails and VERBOSE is set, it will 4679 indicate what the variable should have been set to. 4680 4681`demo-noinst-link.test' 4682 Checks whether libtool will not try to link with a previously 4683 installed version of a library when it should be linking with a 4684 just-built one. 4685 4686`depdemo-conf.test' 4687`depdemo-exec.test' 4688`depdemo-inst.test' 4689`depdemo-make.test' 4690`depdemo-unst.test' 4691`depdemo-static.test' 4692`depdemo-shared.test' 4693`depdemo-nofast.test' 4694 These programs check to see that the `tests/depdemo' subdirectory 4695 of the libtool distribution can be configured, built, installed, 4696 and uninstalled correctly. 4697 4698 The `tests/depdemo' subdirectory contains a demonstration of 4699 inter-library dependencies with libtool. The test programs link 4700 some interdependent libraries. 4701 4702 The tests `depdemo-make.test', `depdemo-exec.test', 4703 `depdemo-inst.test' and `depdemo-unst.test' are executed four 4704 times, under four different libtool configurations: 4705 `depdemo-conf.test' configures `depdemo/libtool' to build both 4706 static and shared libraries, `depdemo-static.test' builds only 4707 static libraries (`--disable-shared'), and `depdemo-shared.test' 4708 builds only shared libraries (`--disable-static'). 4709 `depdemo-nofast.test' configures `depdemo/libtool' to disable the 4710 fast-install mode (`--enable-fast-install=no'). 4711 4712`mdemo-conf.test' 4713`mdemo-exec.test' 4714`mdemo-inst.test' 4715`mdemo-make.test' 4716`mdemo-unst.test' 4717`mdemo-static.test' 4718`mdemo-shared.test' 4719 These programs check to see that the `tests/mdemo' subdirectory of 4720 the libtool distribution can be configured, built, installed, and 4721 uninstalled correctly. 4722 4723 The `tests/mdemo' subdirectory contains a demonstration of a 4724 package that uses libtool and the system independent dlopen wrapper 4725 `libltdl' to load modules. The library `libltdl' provides a 4726 dlopen wrapper for various platforms (Linux, Solaris, HP/UX etc.) 4727 including support for dlpreopened modules (*note Dlpreopening::). 4728 4729 The tests `mdemo-make.test', `mdemo-exec.test', `mdemo-inst.test' 4730 and `mdemo-unst.test' are executed three times, under three 4731 different libtool configurations: `mdemo-conf.test' configures 4732 `mdemo/libtool' to build both static and shared libraries, 4733 `mdemo-static.test' builds only static libraries 4734 (`--disable-shared'), and `mdemo-shared.test' builds only shared 4735 libraries (`--disable-static'). 4736 4737`mdemo-dryrun.test' 4738 This test checks whether libtool's `--dry-run' mode works properly. 4739 4740`mdemo2-conf.test' 4741`mdemo2-exec.test' 4742`mdemo2-make.test' 4743 These programs check to see that the `tests/mdemo2' subdirectory of 4744 the libtool distribution can be configured, built, and executed 4745 correctly. 4746 4747 The `tests/mdemo2' directory contains a demonstration of a package 4748 that attempts to link with a library (from the `tests/mdemo' 4749 directory) that itself does dlopening of libtool modules. 4750 4751`link.test' 4752 This test guarantees that linking directly against a non-libtool 4753 static library works properly. 4754 4755`link-2.test' 4756 This test makes sure that files ending in `.lo' are never linked 4757 directly into a program file. 4758 4759`nomode.test' 4760 Check whether we can actually get help for libtool. 4761 4762`objectlist.test' 4763 Check that a nonexistent objectlist file is properly detected. 4764 4765`pdemo-conf.test' 4766`pdemo-exec.test' 4767`pdemo-inst.test' 4768`pdemo-make.test' 4769 These programs check to see that the `tests/pdemo' subdirectory of 4770 the libtool distribution can be configured, built, and executed 4771 correctly. 4772 4773 The `pdemo-conf.test' lowers the MAX_CMD_LEN variable in the 4774 generated libtool script to test the measures to evade command line 4775 length limitations. 4776 4777`quote.test' 4778 This program checks libtool's metacharacter quoting. 4779 4780`sh.test' 4781 Checks for some nonportable or dubious or undesired shell 4782 constructs in shell scripts. 4783 4784`suffix.test' 4785 When other programming languages are used with libtool (*note 4786 Other languages::), the source files may end in suffixes other 4787 than `.c'. This test validates that libtool can handle suffixes 4788 for all the file types that it supports, and that it fails when 4789 the suffix is invalid. 4790 4791`tagdemo-conf.test' 4792`tagdemo-exec.test' 4793`tagdemo-make.test' 4794`tagdemo-static.test' 4795`tagdemo-shared.test' 4796`tagdemo-undef.test' 4797 These programs check to see that the `tests/tagdemo' subdirectory 4798 of the libtool distribution can be configured, built, and executed 4799 correctly. 4800 4801 The `tests/tagdemo' directory contains a demonstration of a package 4802 that uses libtool's multi-language support through configuration 4803 tags. It generates a library from C++ sources, which is then 4804 linked to a C++ program. 4805 4806`f77demo-conf.test' 4807`f77demo-exec.test' 4808`f77demo-make.test' 4809`f77demo-static.test' 4810`f77demo-shared.test' 4811 These programs check to see that the `tests/f77demo' subdirectory 4812 of the libtool distribution can be configured, built, and executed 4813 correctly. 4814 4815 The `tests/f77demo' tests test Fortran 77 support in libtool by 4816 creating libraries from Fortran 77 sources, and mixed Fortran and C 4817 sources, and a Fortran 77 program to use the former library, and a 4818 C program to use the latter library. 4819 4820`fcdemo-conf.test' 4821`fcdemo-exec.test' 4822`fcdemo-make.test' 4823`fcdemo-static.test' 4824`fcdemo-shared.test' 4825 These programs check to see that the `tests/fcdemo' subdirectory 4826 of the libtool distribution can be configured, built, and executed 4827 correctly. 4828 4829 The `tests/fcdemo' is similar to the `tests/f77demo' directory, 4830 except that Fortran 90 is used in combination with the `FC' 4831 interface provided by Autoconf and Automake. 4832 4833 4834 The new, Autotest-based test suite uses keywords to classify certain 4835test groups: 4836 4837`CXX' 4838`F77' 4839`FC' 4840`GCJ' 4841 The test group exercises one of these `libtool' language tags. 4842 4843`autoconf' 4844`automake' 4845 These keywords denote that the respective external program is 4846 needed by the test group. The tests are typically skipped if the 4847 program is not installed. The `automake' keyword may also denote 4848 use of the `aclocal' program. 4849 4850`interactive' 4851 This test group may require user interaction on some systems. 4852 Typically, this means closing a popup window about a DLL load 4853 error on Windows. 4854 4855`libltdl' 4856 Denote that the `libltdl' library is exercised by the test group. 4857 4858`libtool' 4859`libtoolize' 4860 Denote that the `libtool' or `libtoolize' scripts are exercised by 4861 the test group, respectively. 4862 4863`recursive' 4864 Denote that this test group may recursively re-invoke the test 4865 suite itself, with changed settings and maybe a changed `libtool' 4866 script. You may use the `INNER_TESTSUITEFLAGS' variable to pass 4867 additional settings to this recursive invocation. Typically, 4868 recursive invocations delimit the set of tests with another 4869 keyword, for example by passing `-k libtool' right before the 4870 expansion of the `INNER_TESTSUITEFLAGS' variable (without an 4871 intervening space, so you get the chance for further delimitation). 4872 4873 Test groups with the keyword `recursive' should not be denoted with 4874 keywords, in order to avoid infinite recursion. As a consequence, 4875 recursive test groups themselves should never require user 4876 interaction, while the test groups they invoke may do so. 4877 4878 For example, in order to avoid any interactive test groups, you could 4879use this: 4880 4881 make check-local \ 4882 TESTSUITEFLAGS='-k !interactive INNER_TESTSUITEFLAGS=",!interactive"' 4883 4884while to run only those test groups, you would use this: 4885 4886 make check-local \ 4887 TESTSUITEFLAGS='-k interactive -k recursive INNER_TESTSUITEFLAGS=,interactive' 4888 4889but the convenience targets `check-interactive' and 4890`check-noninteractive' avoid needing to remember these complex 4891commands, in addition to also disabling interactive tests in the old 4892test suite. 4893 4894 4895File: libtool.info, Node: When tests fail, Prev: Test descriptions, Up: Libtool test suite 4896 489714.1.2 When tests fail 4898---------------------- 4899 4900Each of the tests in the old test suite are designed to produce no 4901output when they are run via `make check'. The exit status of each 4902program tells the `Makefile' whether or not the test succeeded. 4903 4904 If a test fails, it means that there is either a programming error in 4905libtool, or in the test program itself. 4906 4907 To investigate a particular test, you may run it directly, as you 4908would a normal program. When the test is invoked in this way, it 4909produces output that may be useful in determining what the problem is. 4910 4911 Another way to have the test programs produce output is to set the 4912VERBOSE environment variable to `yes' before running them. For 4913example, `env VERBOSE=yes make check' runs all the tests, and has each 4914of them display debugging information. 4915 4916 The new, Autotest-based test suite produces as output a file 4917`tests/testsuite.log' which contains information about failed tests. 4918 4919 You can pass options to the test suite through the `make' variable 4920TESTSUITEFLAGS (*note The Autoconf Manual: (autoconf)testsuite 4921Invocation.). 4922 4923 4924File: libtool.info, Node: Reporting bugs, Prev: Libtool test suite, Up: Troubleshooting 4925 492614.2 Reporting bugs 4927=================== 4928 4929If you think you have discovered a bug in libtool, you should think 4930twice: the libtool maintainer is notorious for passing the buck (or 4931maybe that should be "passing the bug"). Libtool was invented to fix 4932known deficiencies in shared library implementations, so, in a way, most 4933of the bugs in libtool are actually bugs in other operating systems. 4934However, the libtool maintainer would definitely be happy to add support 4935for somebody else's buggy operating system. [I wish there was a good 4936way to do winking smiley-faces in Texinfo.] 4937 4938 Genuine bugs in libtool include problems with shell script 4939portability, documentation errors, and failures in the test suite 4940(*note Libtool test suite::). 4941 4942 First, check the documentation and help screens to make sure that the 4943behaviour you think is a problem is not already mentioned as a feature. 4944 4945 Then, you should read the Emacs guide to reporting bugs (*note 4946Reporting Bugs: (emacs)Bugs.). Some of the details listed there are 4947specific to Emacs, but the principle behind them is a general one. 4948 4949 Finally, send a bug report to the Libtool bug reporting address 4950<bug-libtool@gnu.org> with any appropriate _facts_, such as test suite 4951output (*note When tests fail::), all the details needed to reproduce 4952the bug, and a brief description of why you think the behaviour is a 4953bug. Be sure to include the word "libtool" in the subject line, as 4954well as the version number you are using (which can be found by typing 4955`libtool --version'). 4956 4957 4958File: libtool.info, Node: Maintaining, Next: GNU Free Documentation License, Prev: Troubleshooting, Up: Top 4959 496015 Maintenance notes for libtool 4961******************************** 4962 4963This chapter contains information that the libtool maintainer finds 4964important. It will be of no use to you unless you are considering 4965porting libtool to new systems, or writing your own libtool. 4966 4967* Menu: 4968 4969* New ports:: How to port libtool to new systems. 4970* Tested platforms:: When libtool was last tested. 4971* Platform quirks:: Information about different library systems. 4972* libtool script contents:: Configuration information that libtool uses. 4973* Cheap tricks:: Making libtool maintainership easier. 4974 4975 4976File: libtool.info, Node: New ports, Next: Tested platforms, Up: Maintaining 4977 497815.1 Porting libtool to new systems 4979=================================== 4980 4981Before you embark on porting libtool to an unsupported system, it is 4982worthwhile to send e-mail to the Libtool mailing list 4983<libtool@gnu.org>, to make sure that you are not duplicating existing 4984work. 4985 4986 If you find that any porting documentation is missing, please 4987complain! Complaints with patches and improvements to the 4988documentation, or to libtool itself, are more than welcome. 4989 4990* Menu: 4991 4992* Information sources:: Where to find relevant documentation 4993* Porting inter-library dependencies:: Implementation details explained 4994 4995 4996File: libtool.info, Node: Information sources, Next: Porting inter-library dependencies, Up: New ports 4997 499815.1.1 Information sources 4999-------------------------- 5000 5001Once it is clear that a new port is necessary, you'll generally need the 5002following information: 5003 5004canonical system name 5005 You need the output of `config.guess' for this system, so that you 5006 can make changes to the libtool configuration process without 5007 affecting other systems. 5008 5009man pages for `ld' and `cc' 5010 These generally describe what flags are used to generate PIC, to 5011 create shared libraries, and to link against only static 5012 libraries. You may need to follow some cross references to find 5013 the information that is required. 5014 5015man pages for `ld.so', `rtld', or equivalent 5016 These are a valuable resource for understanding how shared 5017 libraries are loaded on the system. 5018 5019man page for `ldconfig', or equivalent 5020 This page usually describes how to install shared libraries. 5021 5022output from `ls -l /lib /usr/lib' 5023 This shows the naming convention for shared libraries on the 5024 system, including which names should be symbolic links. 5025 5026any additional documentation 5027 Some systems have special documentation on how to build and install 5028 shared libraries. 5029 5030 If you know how to program the Bourne shell, then you can complete 5031the port yourself; otherwise, you'll have to find somebody with the 5032relevant skills who will do the work. People on the libtool mailing 5033list are usually willing to volunteer to help you with new ports, so 5034you can send the information to them. 5035 5036 To do the port yourself, you'll definitely need to modify the 5037`libtool.m4' macros in order to make platform-specific changes to the 5038configuration process. You should search that file for the `PORTME' 5039keyword, which will give you some hints on what you'll need to change. 5040In general, all that is involved is modifying the appropriate 5041configuration variables (*note libtool script contents::). 5042 5043 Your best bet is to find an already-supported system that is similar 5044to yours, and make your changes based on that. In some cases, however, 5045your system will differ significantly from every other supported system, 5046and it may be necessary to add new configuration variables, and modify 5047the `ltmain.in' script accordingly. Be sure to write to the mailing 5048list before you make changes to `ltmain.in', since they may have advice 5049on the most effective way of accomplishing what you want. 5050 5051 5052File: libtool.info, Node: Porting inter-library dependencies, Prev: Information sources, Up: New ports 5053 505415.1.2 Porting inter-library dependencies support 5055------------------------------------------------- 5056 5057Since version 1.2c, libtool has re-introduced the ability to do 5058inter-library dependency on some platforms, thanks to a patch by Toshio 5059Kuratomi <badger@prtr-13.ucsc.edu>. Here's a shortened version of the 5060message that contained his patch: 5061 5062 The basic architecture is this: in `libtool.m4', the person who 5063writes libtool makes sure `$deplibs' is included in `$archive_cmds' 5064somewhere and also sets the variable `$deplibs_check_method', and maybe 5065`$file_magic_cmd' when `deplibs_check_method' is file_magic. 5066 5067 `deplibs_check_method' can be one of five things: 5068`file_magic [REGEX]' 5069 looks in the library link path for libraries that have the right 5070 libname. Then it runs `$file_magic_cmd' on the library and checks 5071 for a match against the extended regular expression REGEX. When 5072 FILE_MAGIC_TEST_FILE is set by `libtool.m4', it is used as an 5073 argument to `$file_magic_cmd' in order to verify whether the 5074 regular expression matches its output, and warn the user otherwise. 5075 5076`test_compile' 5077 just checks whether it is possible to link a program out of a list 5078 of libraries, and checks which of those are listed in the output of 5079 `ldd'. It is currently unused, and will probably be dropped in the 5080 future. 5081 5082`pass_all' 5083 will pass everything without any checking. This may work on 5084 platforms in which code is position-independent by default and 5085 inter-library dependencies are properly supported by the dynamic 5086 linker, for example, on DEC OSF/1 3 and 4. 5087 5088`none' 5089 It causes deplibs to be reassigned `deplibs=""'. That way 5090 `archive_cmds' can contain deplibs on all platforms, but not have 5091 deplibs used unless needed. 5092 5093`unknown' 5094 is the default for all systems unless overridden in `libtool.m4'. 5095 It is the same as `none', but it documents that we really don't 5096 know what the correct value should be, and we welcome patches that 5097 improve it. 5098 5099 Then in `ltmain.in' we have the real workhorse: a little 5100initialization and postprocessing (to setup/release variables for use 5101with eval echo libname_spec etc.) and a case statement that decides the 5102method that is being used. This is the real code... I wish I could 5103condense it a little more, but I don't think I can without function 5104calls. I've mostly optimized it (moved things out of loops, etc.) but 5105there is probably some fat left. I thought I should stop while I was 5106ahead, work on whatever bugs you discover, etc. before thinking about 5107more than obvious optimizations. 5108 5109 5110File: libtool.info, Node: Tested platforms, Next: Platform quirks, Prev: New ports, Up: Maintaining 5111 511215.2 Tested platforms 5113===================== 5114 5115This table describes when libtool was last known to be tested on 5116platforms where it claims to support shared libraries: 5117 5118 ------------------------------------------------------- 5119 canonical host name compiler libtool results 5120 (tools versions) release 5121 ------------------------------------------------------- 5122 alpha-dec-osf5.1 cc 1.3e ok (1.910) 5123 alpha-dec-osf4.0f gcc 1.3e ok (1.910) 5124 alpha-dec-osf4.0f cc 1.3e ok (1.910) 5125 alpha-dec-osf3.2 gcc 0.8 ok 5126 alpha-dec-osf3.2 cc 0.8 ok 5127 alpha-dec-osf2.1 gcc 1.2f NS 5128 alpha*-unknown-linux-gnu gcc 1.3b ok 5129 (egcs-1.1.2, GNU ld 2.9.1.0.23) 5130 hppa2.0w-hp-hpux11.00 cc 1.2f ok 5131 hppa2.0-hp-hpux10.20 cc 1.3.2 ok 5132 hppa1.1-hp-hpux10.20 gcc 1.2f ok 5133 hppa1.1-hp-hpux10.20 cc 1.3c ok (1.821) 5134 hppa1.1-hp-hpux10.10 gcc 1.2f ok 5135 hppa1.1-hp-hpux10.10 cc 1.2f ok 5136 hppa1.1-hp-hpux9.07 gcc 1.2f ok 5137 hppa1.1-hp-hpux9.07 cc 1.2f ok 5138 hppa1.1-hp-hpux9.05 gcc 1.2f ok 5139 hppa1.1-hp-hpux9.05 cc 1.2f ok 5140 hppa1.1-hp-hpux9.01 gcc 1.2f ok 5141 hppa1.1-hp-hpux9.01 cc 1.2f ok 5142 i*86-*-beos gcc 1.2f ok 5143 i*86-*-bsdi4.0.1 gcc 1.3c ok 5144 (gcc-2.7.2.1) 5145 i*86-*-bsdi4.0 gcc 1.2f ok 5146 i*86-*-bsdi3.1 gcc 1.2e NS 5147 i*86-*-bsdi3.0 gcc 1.2e NS 5148 i*86-*-bsdi2.1 gcc 1.2e NS 5149 i*86-pc-cygwin gcc 1.3b NS 5150 (egcs-1.1 stock b20.1 compiler) 5151 i*86-*-dguxR4.20MU01 gcc 1.2 ok 5152 i*86-*-freebsd4.3 gcc 1.3e ok (1.912) 5153 i*86-*-freebsdelf4.0 gcc 1.3c ok 5154 (egcs-1.1.2) 5155 i*86-*-freebsdelf3.2 gcc 1.3c ok 5156 (gcc-2.7.2.1) 5157 i*86-*-freebsdelf3.1 gcc 1.3c ok 5158 (gcc-2.7.2.1) 5159 i*86-*-freebsdelf3.0 gcc 1.3c ok 5160 i*86-*-freebsd3.0 gcc 1.2e ok 5161 i*86-*-freebsd2.2.8 gcc 1.3c ok 5162 (gcc-2.7.2.1) 5163 i*86-*-freebsd2.2.6 gcc 1.3b ok 5164 (egcs-1.1 & gcc-2.7.2.1, native ld) 5165 i*86-*-freebsd2.1.5 gcc 0.5 ok 5166 i*86-*-netbsd1.5 gcc 1.3e ok (1.901) 5167 (egcs-1.1.2) 5168 i*86-*-netbsd1.4 gcc 1.3c ok 5169 (egcs-1.1.1) 5170 i*86-*-netbsd1.4.3A gcc 1.3e ok (1.901) 5171 i*86-*-netbsd1.3.3 gcc 1.3c ok 5172 (gcc-2.7.2.2+myc2) 5173 i*86-*-netbsd1.3.2 gcc 1.2e ok 5174 i*86-*-netbsd1.3I gcc 1.2e ok 5175 (egcs 1.1?) 5176 i*86-*-netbsd1.2 gcc 0.9g ok 5177 i*86-*-linux-gnu gcc 1.3e ok (1.901) 5178 (Red Hat 7.0, gcc "2.96") 5179 i*86-*-linux-gnu gcc 1.3e ok (1.911) 5180 (SuSE 7.0, gcc 2.95.2) 5181 i*86-*-linux-gnulibc1 gcc 1.2f ok 5182 i*86-*-openbsd2.5 gcc 1.3c ok 5183 (gcc-2.8.1) 5184 i*86-*-openbsd2.4 gcc 1.3c ok 5185 (gcc-2.8.1) 5186 i*86-*-solaris2.7 gcc 1.3b ok 5187 (egcs-1.1.2, native ld) 5188 i*86-*-solaris2.6 gcc 1.2f ok 5189 i*86-*-solaris2.5.1 gcc 1.2f ok 5190 i*86-ncr-sysv4.3.03 gcc 1.2f ok 5191 i*86-ncr-sysv4.3.03 cc 1.2e ok 5192 (cc -Hnocopyr) 5193 i*86-pc-sco3.2v5.0.5 cc 1.3c ok 5194 i*86-pc-sco3.2v5.0.5 gcc 1.3c ok 5195 (gcc 95q4c) 5196 i*86-pc-sco3.2v5.0.5 gcc 1.3c ok 5197 (egcs-1.1.2) 5198 i*86-sco-sysv5uw7.1.1 gcc 1.3e ok (1.901) 5199 (gcc-2.95.2, SCO linker) 5200 i*86-UnixWare7.1.0-sysv5 cc 1.3c ok 5201 i*86-UnixWare7.1.0-sysv5 gcc 1.3c ok 5202 (egcs-1.1.1) 5203 m68k-next-nextstep3 gcc 1.2f NS 5204 m68k-sun-sunos4.1.1 gcc 1.2f NS 5205 (gcc-2.5.7) 5206 m88k-dg-dguxR4.12TMU01 gcc 1.2 ok 5207 m88k-motorola-sysv4 gcc 1.3 ok 5208 (egcs-1.1.2) 5209 mips-sgi-irix6.5 gcc 1.2f ok 5210 (gcc-2.8.1) 5211 mips-sgi-irix6.4 gcc 1.2f ok 5212 mips-sgi-irix6.3 gcc 1.3b ok 5213 (egcs-1.1.2, native ld) 5214 mips-sgi-irix6.3 cc 1.3b ok 5215 (cc 7.0) 5216 mips-sgi-irix6.2 gcc 1.2f ok 5217 mips-sgi-irix6.2 cc 0.9 ok 5218 mips-sgi-irix5.3 gcc 1.2f ok 5219 (egcs-1.1.1) 5220 mips-sgi-irix5.3 gcc 1.2f NS 5221 (gcc-2.6.3) 5222 mips-sgi-irix5.3 cc 0.8 ok 5223 mips-sgi-irix5.2 gcc 1.3b ok 5224 (egcs-1.1.2, native ld) 5225 mips-sgi-irix5.2 cc 1.3b ok 5226 (cc 3.18) 5227 mips-sni-sysv4 cc 1.3.5 ok 5228 (Siemens C-compiler) 5229 mips-sni-sysv4 gcc 1.3.5 ok 5230 (gcc-2.7.2.3, GNU assembler 2.8.1, native ld) 5231 mipsel-unknown-openbsd2.1 gcc 1.0 ok 5232 powerpc-apple-darwin6.4 gcc 1.5 ok 5233 (apple dev tools released 12/2002) 5234 powerpc-ibm-aix4.3.1.0 gcc 1.2f ok 5235 (egcs-1.1.1) 5236 powerpc-ibm-aix4.2.1.0 gcc 1.2f ok 5237 (egcs-1.1.1) 5238 powerpc-ibm-aix4.1.5.0 gcc 1.2f ok 5239 (egcs-1.1.1) 5240 powerpc-ibm-aix4.1.5.0 gcc 1.2f NS 5241 (gcc-2.8.1) 5242 powerpc-ibm-aix4.1.4.0 gcc 1.0 ok 5243 powerpc-ibm-aix4.1.4.0 xlc 1.0i ok 5244 rs6000-ibm-aix4.1.5.0 gcc 1.2f ok 5245 (gcc-2.7.2) 5246 rs6000-ibm-aix4.1.4.0 gcc 1.2f ok 5247 (gcc-2.7.2) 5248 rs6000-ibm-aix3.2.5 gcc 1.0i ok 5249 rs6000-ibm-aix3.2.5 xlc 1.0i ok 5250 sparc-sun-solaris2.8 gcc 1.3e ok (1.913) 5251 (gcc-2.95.3 & native ld) 5252 sparc-sun-solaris2.7 gcc 1.3e ok (1.913) 5253 (gcc-2.95.3 & native ld) 5254 sparc-sun-solaris2.6 gcc 1.3e ok (1.913) 5255 (gcc-2.95.3 & native ld) 5256 sparc-sun-solaris2.5.1 gcc 1.3e ok (1.911) 5257 sparc-sun-solaris2.5 gcc 1.3b ok 5258 (egcs-1.1.2, GNU ld 2.9.1 & native ld) 5259 sparc-sun-solaris2.5 cc 1.3b ok 5260 (SC 3.0.1) 5261 sparc-sun-solaris2.4 gcc 1.0a ok 5262 sparc-sun-solaris2.4 cc 1.0a ok 5263 sparc-sun-solaris2.3 gcc 1.2f ok 5264 sparc-sun-sunos4.1.4 gcc 1.2f ok 5265 sparc-sun-sunos4.1.4 cc 1.0f ok 5266 sparc-sun-sunos4.1.3_U1 gcc 1.2f ok 5267 sparc-sun-sunos4.1.3C gcc 1.2f ok 5268 sparc-sun-sunos4.1.3 gcc 1.3b ok 5269 (egcs-1.1.2, GNU ld 2.9.1 & native ld) 5270 sparc-sun-sunos4.1.3 cc 1.3b ok 5271 sparc-unknown-bsdi4.0 gcc 1.2c ok 5272 sparc-unknown-linux-gnulibc1 gcc 1.2f ok 5273 sparc-unknown-linux-gnu gcc 1.3b ok 5274 (egcs-1.1.2, GNU ld 2.9.1.0.23) 5275 sparc64-unknown-linux-gnu gcc 1.2f ok 5276 5277 Notes: 5278 - "ok" means "all tests passed". 5279 - "NS" means "Not Shared", but OK for static libraries 5280 5281 Note: The vendor-distributed HP-UX `sed'(1) programs are horribly 5282broken, and cannot handle libtool's requirements, so users may report 5283unusual problems. There is no workaround except to install a working 5284`sed' (such as GNU `sed') on these systems. 5285 5286 Note: The vendor-distributed NCR MP-RAS `cc' programs emits 5287copyright on standard error that confuse tests on size of 5288`conftest.err'. The workaround is to specify `CC' when run `configure' 5289with `CC='cc -Hnocopyr''. 5290 5291 5292File: libtool.info, Node: Platform quirks, Next: libtool script contents, Prev: Tested platforms, Up: Maintaining 5293 529415.3 Platform quirks 5295==================== 5296 5297This section is dedicated to the sanity of the libtool maintainers. It 5298describes the programs that libtool uses, how they vary from system to 5299system, and how to test for them. 5300 5301 Because libtool is a shell script, it can be difficult to understand 5302just by reading it from top to bottom. This section helps show why 5303libtool does things a certain way. Combined with the scripts 5304themselves, you should have a better sense of how to improve libtool, or 5305write your own. 5306 5307* Menu: 5308 5309* References:: Finding more information. 5310* Compilers:: Creating object files from source files. 5311* Reloadable objects:: Binding object files together. 5312* Multiple dependencies:: Removing duplicate dependent libraries. 5313* Archivers:: Programs that create static archives. 5314 5315 5316File: libtool.info, Node: References, Next: Compilers, Up: Platform quirks 5317 531815.3.1 References 5319----------------- 5320 5321The following is a list of valuable documentation references: 5322 5323 * SGI's IRIX Manual Pages can be found at 5324 `http://techpubs.sgi.com/cgi-bin/infosrch.cgi?cmd=browse&db=man'. 5325 5326 * Sun's free service area 5327 (`http://www.sun.com/service/online/free.html') and documentation 5328 server (`http://docs.sun.com/'). 5329 5330 * Compaq's Tru64 UNIX online documentation is at 5331 (`http://tru64unix.compaq.com/faqs/publications/pub_page/doc_list.html') 5332 with C++ documentation at 5333 (`http://tru64unix.compaq.com/cplus/docs/index.htm'). 5334 5335 * Hewlett-Packard has online documentation at 5336 (`http://docs.hp.com/index.html'). 5337 5338 * IBM has online documentation at 5339 (`http://www.rs6000.ibm.com/resource/aix_resource/Pubs/'). 5340 5341 5342File: libtool.info, Node: Compilers, Next: Reloadable objects, Prev: References, Up: Platform quirks 5343 534415.3.2 Compilers 5345---------------- 5346 5347The only compiler characteristics that affect libtool are the flags 5348needed (if any) to generate PIC objects. In general, if a C compiler 5349supports certain PIC flags, then any derivative compilers support the 5350same flags. Until there are some noteworthy exceptions to this rule, 5351this section will document only C compilers. 5352 5353 The following C compilers have standard command line options, 5354regardless of the platform: 5355 5356`gcc' 5357 This is the GNU C compiler, which is also the system compiler for 5358 many free operating systems (FreeBSD, GNU/Hurd, GNU/Linux, Lites, 5359 NetBSD, and OpenBSD, to name a few). 5360 5361 The `-fpic' or `-fPIC' flags can be used to generate 5362 position-independent code. `-fPIC' is guaranteed to generate 5363 working code, but the code is slower on m68k, m88k, and Sparc 5364 chips. However, using `-fpic' on those chips imposes arbitrary 5365 size limits on the shared libraries. 5366 5367 The rest of this subsection lists compilers by the operating system 5368that they are bundled with: 5369 5370`aix3*' 5371`aix4*' 5372 Most AIX compilers have no PIC flags, since AIX (with the 5373 exception of AIX for IA-64) runs on PowerPC and RS/6000 chips. (1) 5374 5375`hpux10*' 5376 Use `+Z' to generate PIC. 5377 5378`osf3*' 5379 Digital/UNIX 3.x does not have PIC flags, at least not on the 5380 PowerPC platform. 5381 5382`solaris2*' 5383 Use `-KPIC' to generate PIC. 5384 5385`sunos4*' 5386 Use `-PIC' to generate PIC. 5387 5388 ---------- Footnotes ---------- 5389 5390 (1) All code compiled for the PowerPC and RS/6000 chips 5391(`powerpc-*-*', `powerpcle-*-*', and `rs6000-*-*') is 5392position-independent, regardless of the operating system or compiler 5393suite. So, "regular objects" can be used to build shared libraries on 5394these systems and no special PIC compiler flags are required. 5395 5396 5397File: libtool.info, Node: Reloadable objects, Next: Multiple dependencies, Prev: Compilers, Up: Platform quirks 5398 539915.3.3 Reloadable objects 5400------------------------- 5401 5402On all known systems, a reloadable object can be created by running `ld 5403-r -o OUTPUT.o INPUT1.o INPUT2.o'. This reloadable object may be 5404treated as exactly equivalent to other objects. 5405 5406 5407File: libtool.info, Node: Multiple dependencies, Next: Archivers, Prev: Reloadable objects, Up: Platform quirks 5408 540915.3.4 Multiple dependencies 5410---------------------------- 5411 5412On most modern platforms the order in which dependent libraries are 5413listed has no effect on object generation. In theory, there are 5414platforms that require libraries that provide missing symbols to other 5415libraries to be listed after those libraries whose symbols they provide. 5416 5417 Particularly, if a pair of static archives each resolve some of the 5418other's symbols, it might be necessary to list one of those archives 5419both before and after the other one. Libtool does not currently cope 5420with this situation well, since duplicate libraries are removed from 5421the link line by default. Libtool provides the command line option 5422`--preserve-dup-deps' to preserve all duplicate dependencies in cases 5423where it is necessary. 5424 5425 5426File: libtool.info, Node: Archivers, Prev: Multiple dependencies, Up: Platform quirks 5427 542815.3.5 Archivers 5429---------------- 5430 5431On all known systems, building a static library can be accomplished by 5432running `ar cru libNAME.a OBJ1.o OBJ2.o ...', where the `.a' file is 5433the output library, and each `.o' file is an object file. 5434 5435 On all known systems, if there is a program named `ranlib', then it 5436must be used to "bless" the created library before linking against it, 5437with the `ranlib libNAME.a' command. Some systems, like Irix, use the 5438`ar ts' command, instead. 5439 5440 5441File: libtool.info, Node: libtool script contents, Next: Cheap tricks, Prev: Platform quirks, Up: Maintaining 5442 544315.4 `libtool' script contents 5444============================== 5445 5446Since version 1.4, the `libtool' script is generated by `configure' 5447(*note Configuring::). In earlier versions, `configure' achieved this 5448by calling a helper script called `ltconfig'. From libtool version 0.7 5449to 1.0, this script simply set shell variables, then sourced the 5450libtool backend, `ltmain.sh'. `ltconfig' from libtool version 1.1 5451through 1.3 inlined the contents of `ltmain.sh' into the generated 5452`libtool', which improved performance on many systems. The tests that 5453`ltconfig' used to perform are now kept in `libtool.m4' where they can 5454be written using Autoconf. This has the runtime performance benefits 5455of inlined `ltmain.sh', _and_ improves the build time a little while 5456considerably easing the amount of raw shell code that used to need 5457maintaining. 5458 5459 The convention used for naming variables that hold shell commands for 5460delayed evaluation, is to use the suffix `_cmd' where a single line of 5461valid shell script is needed, and the suffix `_cmds' where multiple 5462lines of shell script *may* be delayed for later evaluation. By 5463convention, `_cmds' variables delimit the evaluation units with the `~' 5464character where necessary. 5465 5466 Here is a listing of each of the configuration variables, and how 5467they are used within `ltmain.sh' (*note Configuring::): 5468 5469 -- Variable: AR 5470 The name of the system library archiver. 5471 5472 -- Variable: CC 5473 The name of the compiler used to configure libtool. This will 5474 always contain the compiler for the current language (*note 5475 Tags::). 5476 5477 -- Variable: ECHO 5478 An `echo' program that does not interpret backslashes as an escape 5479 character. It may be given only one argument, so due quoting is 5480 necessary. 5481 5482 -- Variable: LD 5483 The name of the linker that libtool should use internally for 5484 reloadable linking and possibly shared libraries. 5485 5486 -- Variable: LTCC 5487 -- Variable: LTCFLAGS 5488 The name of the C compiler and C compiler flags used to configure 5489 libtool. 5490 5491 -- Variable: NM 5492 The name of a BSD- or MS-compatible program that produces listings 5493 of global symbols. For BSD `nm', the symbols should be in one the 5494 following formats: 5495 5496 ADDRESS C GLOBAL-VARIABLE-NAME 5497 ADDRESS D GLOBAL-VARIABLE-NAME 5498 ADDRESS T GLOBAL-FUNCTION-NAME 5499 5500 For MS `dumpbin', the symbols should be in one of the following 5501 formats: 5502 5503 COUNTER SIZE UNDEF notype External | GLOBAL-VAR 5504 COUNTER ADDRESS SECTION notype External | GLOBAL-VAR 5505 COUNTER ADDRESS SECTION notype () External | GLOBAL-FUNC 5506 5507 The SIZE of the global variables are not zero and the SECTION of 5508 the global functions are not "UNDEF". Symbols in "pick any" 5509 sections ("pick any" appears in the section header) are not global 5510 either. 5511 5512 -- Variable: RANLIB 5513 Set to the name of the `ranlib' program, if any. 5514 5515 -- Variable: allow_undefined_flag 5516 The flag that is used by `archive_cmds' in order to declare that 5517 there will be unresolved symbols in the resulting shared library. 5518 Empty, if no such flag is required. Set to `unsupported' if there 5519 is no way to generate a shared library with references to symbols 5520 that aren't defined in that library. 5521 5522 -- Variable: always_export_symbols 5523 Whether libtool should automatically generate a list of exported 5524 symbols using EXPORT_SYMBOLS_CMDS before linking an archive. Set 5525 to `yes' or `no'. Default is `no'. 5526 5527 -- Variable: archive_cmds 5528 -- Variable: archive_expsym_cmds 5529 -- Variable: old_archive_cmds 5530 Commands used to create shared libraries, shared libraries with 5531 `-export-symbols' and static libraries, respectively. 5532 5533 -- Variable: old_archive_from_new_cmds 5534 If the shared library depends on a static library, 5535 `old_archive_from_new_cmds' contains the commands used to create 5536 that static library. If this variable is not empty, 5537 `old_archive_cmds' is not used. 5538 5539 -- Variable: old_archive_from_expsyms_cmds 5540 If a static library must be created from the export symbol list in 5541 order to correctly link with a shared library, 5542 `old_archive_from_expsyms_cmds' contains the commands needed to 5543 create that static library. When these commands are executed, the 5544 variable SONAME contains the name of the shared library in 5545 question, and the $OBJDIR/$NEWLIB contains the path of the static 5546 library these commands should build. After executing these 5547 commands, libtool will proceed to link against $OBJDIR/$NEWLIB 5548 instead of SONAME. 5549 5550 -- Variable: lock_old_archive_extraction 5551 Set to `yes' if the extraction of a static library requires locking 5552 the library file. This is required on Darwin. 5553 5554 -- Variable: build 5555 -- Variable: build_alias 5556 -- Variable: build_os 5557 Set to the specified and canonical names of the system that 5558 libtool was built on. 5559 5560 -- Variable: build_libtool_libs 5561 Whether libtool should build shared libraries on this system. Set 5562 to `yes' or `no'. 5563 5564 -- Variable: build_old_libs 5565 Whether libtool should build static libraries on this system. Set 5566 to `yes' or `no'. 5567 5568 -- Variable: compiler_c_o 5569 Whether the compiler supports the `-c' and `-o' options 5570 simultaneously. Set to `yes' or `no'. 5571 5572 -- Variable: compiler_needs_object 5573 Whether the compiler has to see an object listed on the command 5574 line in order to successfully invoke the linker. If `no', then a 5575 set of convenience archives or a set of object file names can be 5576 passed via linker-specific options or linker scripts. 5577 5578 -- Variable: dlopen_support 5579 Whether `dlopen' is supported on the platform. Set to `yes' or 5580 `no'. 5581 5582 -- Variable: dlopen_self 5583 Whether it is possible to `dlopen' the executable itself. Set to 5584 `yes' or `no'. 5585 5586 -- Variable: dlopen_self_static 5587 Whether it is possible to `dlopen' the executable itself, when it 5588 is linked statically (`-all-static'). Set to `yes' or `no'. 5589 5590 -- Variable: exclude_expsyms 5591 List of symbols that should not be listed in the preloaded symbols. 5592 5593 -- Variable: export_dynamic_flag_spec 5594 Compiler link flag that allows a dlopened shared library to 5595 reference symbols that are defined in the program. 5596 5597 -- Variable: export_symbols_cmds 5598 Commands to extract exported symbols from LIBOBJS to the file 5599 EXPORT_SYMBOLS. 5600 5601 -- Variable: extract_expsyms_cmds 5602 Commands to extract the exported symbols list from a shared 5603 library. These commands are executed if there is no file 5604 $OBJDIR/$SONAME-DEF, and should write the names of the exported 5605 symbols to that file, for the use of 5606 `old_archive_from_expsyms_cmds'. 5607 5608 -- Variable: fast_install 5609 Determines whether libtool will privilege the installer or the 5610 developer. The assumption is that installers will seldom run 5611 programs in the build tree, and the developer will seldom install. 5612 This is only meaningful on platforms where 5613 SHLIBPATH_OVERRIDES_RUNPATH is not `yes', so FAST_INSTALL will be 5614 set to `needless' in this case. If FAST_INSTALL set to `yes', 5615 libtool will create programs that search for installed libraries, 5616 and, if a program is run in the build tree, a new copy will be 5617 linked on-demand to use the yet-to-be-installed libraries. If set 5618 to `no', libtool will create programs that use the 5619 yet-to-be-installed libraries, and will link a new copy of the 5620 program at install time. The default value is `yes' or 5621 `needless', depending on platform and configuration flags, and it 5622 can be turned from `yes' to `no' with the configure flag 5623 `--disable-fast-install'. 5624 5625 On some systems, the linker always hardcodes paths to dependent 5626 libraries into the output. In this case, FAST_INSTALL is never 5627 set to `yes', and relinking at install time is triggered. This 5628 also means that DESTDIR installation does not work as expected. 5629 5630 -- Variable: finish_cmds 5631 Commands to tell the dynamic linker how to find shared libraries 5632 in a specific directory. 5633 5634 -- Variable: finish_eval 5635 Same as FINISH_CMDS, except the commands are not displayed. 5636 5637 -- Variable: fix_srcfile_path 5638 Expression to fix the shell variable `$srcfile' for the compiler. 5639 5640 -- Variable: global_symbol_pipe 5641 A pipeline that takes the output of NM, and produces a listing of 5642 raw symbols followed by their C names. For example: 5643 5644 $ eval "$NM progname | $global_symbol_pipe" 5645 D SYMBOL1 C-SYMBOL1 5646 T SYMBOL2 C-SYMBOL2 5647 C SYMBOL3 C-SYMBOL3 5648 ... 5649 $ 5650 5651 The first column contains the symbol type (used to tell data from 5652 code) but its meaning is system dependent. 5653 5654 -- Variable: global_symbol_to_cdecl 5655 A pipeline that translates the output of GLOBAL_SYMBOL_PIPE into 5656 proper C declarations. Since some platforms, such as HP/UX, have 5657 linkers that differentiate code from data, data symbols are 5658 declared as data, and code symbols are declared as functions. 5659 5660 -- Variable: hardcode_action 5661 Either `immediate' or `relink', depending on whether shared 5662 library paths can be hardcoded into executables before they are 5663 installed, or if they need to be relinked. 5664 5665 -- Variable: hardcode_direct 5666 Set to `yes' or `no', depending on whether the linker hardcodes 5667 directories if a library is directly specified on the command line 5668 (such as `DIR/libNAME.a') when HARDCODE_LIBDIR_FLAG_SPEC is 5669 specified. 5670 5671 -- Variable: hardcode_direct_absolute 5672 Some architectures hardcode "absolute" library directories that 5673 can not be overridden by SHLIBPATH_VAR when HARDCODE_DIRECT is 5674 `yes'. In that case set HARDCODE_DIRECT_ABSOLUTE to `yes', or 5675 otherwise `no'. 5676 5677 -- Variable: hardcode_into_libs 5678 Whether the platform supports hardcoding of run-paths into 5679 libraries. If enabled, linking of programs will be much simpler 5680 but libraries will need to be relinked during installation. Set 5681 to `yes' or `no'. 5682 5683 -- Variable: hardcode_libdir_flag_spec 5684 Flag to hardcode a LIBDIR variable into a binary, so that the 5685 dynamic linker searches LIBDIR for shared libraries at runtime. 5686 If it is empty, libtool will try to use some other hardcoding 5687 mechanism. 5688 5689 -- Variable: hardcode_libdir_separator 5690 If the compiler only accepts a single HARDCODE_LIBDIR_FLAG, then 5691 this variable contains the string that should separate multiple 5692 arguments to that flag. 5693 5694 -- Variable: hardcode_minus_L 5695 Set to `yes' or `no', depending on whether the linker hardcodes 5696 directories specified by `-L' flags into the resulting executable 5697 when HARDCODE_LIBDIR_FLAG_SPEC is specified. 5698 5699 -- Variable: hardcode_shlibpath_var 5700 Set to `yes' or `no', depending on whether the linker hardcodes 5701 directories by writing the contents of `$shlibpath_var' into the 5702 resulting executable when HARDCODE_LIBDIR_FLAG_SPEC is specified. 5703 Set to `unsupported' if directories specified by `$shlibpath_var' 5704 are searched at run time, but not at link time. 5705 5706 -- Variable: host 5707 -- Variable: host_alias 5708 -- Variable: host_os 5709 Set to the specified and canonical names of the system that 5710 libtool was configured for. 5711 5712 -- Variable: include_expsyms 5713 List of symbols that must always be exported when using 5714 EXPORT_SYMBOLS. 5715 5716 -- Variable: inherit_rpath 5717 Whether the linker adds runtime paths of dependency libraries to 5718 the runtime path list, requiring libtool to relink the output when 5719 installing. Set to `yes' or `no'. Default is `no'. 5720 5721 -- Variable: install_override_mode 5722 Permission mode override for installation of shared libraries. If 5723 the runtime linker fails to load libraries with wrong permissions, 5724 then it may fail to execute programs that are needed during 5725 installation, because these need the library that has just been 5726 installed. In this case, it is necessary to pass the mode to 5727 `install' with `-m INSTALL_OVERRIDE_MODE'. 5728 5729 -- Variable: libext 5730 The standard old archive suffix (normally `a'). 5731 5732 -- Variable: libname_spec 5733 The format of a library name prefix. On all Unix systems, static 5734 libraries are called `libNAME.a', but on some systems (such as 5735 OS/2 or MS-DOS), the library is just called `NAME.a'. 5736 5737 -- Variable: library_names_spec 5738 A list of shared library names. The first is the name of the file, 5739 the rest are symbolic links to the file. The name in the list is 5740 the file name that the linker finds when given `-lNAME'. 5741 5742 -- Variable: link_all_deplibs 5743 Whether libtool must link a program against all its dependency 5744 libraries. Set to `yes' or `no'. Default is `unknown', which is 5745 a synonym for `yes'. 5746 5747 -- Variable: link_static_flag 5748 Linker flag (passed through the C compiler) used to prevent dynamic 5749 linking. 5750 5751 -- Variable: macro_version 5752 -- Variable: macro_revision 5753 The release and revision from which the libtool.m4 macros were 5754 taken. This is used to ensure that macros and `ltmain.sh' 5755 correspond to the same Libtool version. 5756 5757 -- Variable: max_cmd_len 5758 The approximate longest command line that can be passed to `$SHELL' 5759 without being truncated, as computed by `LT_CMD_MAX_LEN'. 5760 5761 -- Variable: need_lib_prefix 5762 Whether we can `dlopen' modules without a `lib' prefix. Set to 5763 `yes' or `no'. By default, it is `unknown', which means the same 5764 as `yes', but documents that we are not really sure about it. 5765 `no' means that it is possible to `dlopen' a module without the 5766 `lib' prefix. 5767 5768 -- Variable: need_version 5769 Whether versioning is required for libraries, i.e. whether the 5770 dynamic linker requires a version suffix for all libraries. Set 5771 to `yes' or `no'. By default, it is `unknown', which means the 5772 same as `yes', but documents that we are not really sure about it. 5773 5774 -- Variable: need_locks 5775 Whether files must be locked to prevent conflicts when compiling 5776 simultaneously. Set to `yes' or `no'. 5777 5778 -- Variable: no_builtin_flag 5779 Compiler flag to disable builtin functions that conflict with 5780 declaring external global symbols as `char'. 5781 5782 -- Variable: no_undefined_flag 5783 The flag that is used by `archive_cmds' in order to declare that 5784 there will be no unresolved symbols in the resulting shared 5785 library. Empty, if no such flag is required. 5786 5787 -- Variable: objdir 5788 The name of the directory that contains temporary libtool files. 5789 5790 -- Variable: objext 5791 The standard object file suffix (normally `o'). 5792 5793 -- Variable: pic_flag 5794 Any additional compiler flags for building library object files. 5795 5796 -- Variable: postinstall_cmds 5797 -- Variable: old_postinstall_cmds 5798 Commands run after installing a shared or static library, 5799 respectively. 5800 5801 -- Variable: postuninstall_cmds 5802 -- Variable: old_postuninstall_cmds 5803 Commands run after uninstalling a shared or static library, 5804 respectively. 5805 5806 -- Variable: reload_cmds 5807 -- Variable: reload_flag 5808 Commands to create a reloadable object. 5809 5810 -- Variable: runpath_var 5811 The environment variable that tells the linker which directories to 5812 hardcode in the resulting executable. 5813 5814 -- Variable: shlibpath_overrides_runpath 5815 Indicates whether it is possible to override the hard-coded library 5816 search path of a program with an environment variable. If this is 5817 set to no, libtool may have to create two copies of a program in 5818 the build tree, one to be installed and one to be run in the build 5819 tree only. When each of these copies is created depends on the 5820 value of `fast_install'. The default value is `unknown', which is 5821 equivalent to `no'. 5822 5823 -- Variable: shlibpath_var 5824 The environment variable that tells the dynamic linker where to 5825 find shared libraries. 5826 5827 -- Variable: soname_spec 5828 The name coded into shared libraries, if different from the real 5829 name of the file. 5830 5831 -- Variable: striplib 5832 -- Variable: old_striplib 5833 Command to strip a shared (`striplib') or static (`old_striplib') 5834 library, respectively. If these variables are empty, the strip 5835 flag in the install mode will be ignored for libraries (*note 5836 Install mode::). 5837 5838 -- Variable: sys_lib_dlsearch_path_spec 5839 Expression to get the run-time system library search path. 5840 Directories that appear in this list are never hard-coded into 5841 executables. 5842 5843 -- Variable: sys_lib_search_path_spec 5844 Expression to get the compile-time system library search path. 5845 This variable is used by libtool when it has to test whether a 5846 certain library is shared or static. The directories listed in 5847 SHLIBPATH_VAR are automatically appended to this list, every time 5848 libtool runs (i.e., not at configuration time), because some 5849 linkers use this variable to extend the library search path. 5850 Linker switches such as `-L' also augment the search path. 5851 5852 -- Variable: thread_safe_flag_spec 5853 Linker flag (passed through the C compiler) used to generate 5854 thread-safe libraries. 5855 5856 -- Variable: version_type 5857 The library version numbering type. One of `libtool', 5858 `freebsd-aout', `freebsd-elf', `irix', `linux', `osf', `sunos', 5859 `windows', or `none'. 5860 5861 -- Variable: whole_archive_flag_spec 5862 Compiler flag to generate shared objects from convenience archives. 5863 5864 -- Variable: wl 5865 The C compiler flag that allows libtool to pass a flag directly to 5866 the linker. Used as: `${wl}SOME-FLAG'. 5867 5868 Variables ending in `_cmds' or `_eval' contain a `~'-separated list 5869of commands that are `eval'ed one after another. If any of the 5870commands return a nonzero exit status, libtool generally exits with an 5871error message. 5872 5873 Variables ending in `_spec' are `eval'ed before being used by 5874libtool. 5875 5876 5877File: libtool.info, Node: Cheap tricks, Prev: libtool script contents, Up: Maintaining 5878 587915.5 Cheap tricks 5880================= 5881 5882Here are a few tricks that you can use in order to make maintainership 5883easier: 5884 5885 * When people report bugs, ask them to use the `--config', 5886 `--debug', or `--features' flags, if you think they will help you. 5887 These flags are there to help you get information directly, rather 5888 than having to trust second-hand observation. 5889 5890 * Rather than reconfiguring libtool every time I make a change to 5891 `ltmain.in', I keep a permanent `libtool' script in my PATH, which 5892 sources `ltmain.in' directly. 5893 5894 The following steps describe how to create such a script, where 5895 `/home/src/libtool' is the directory containing the libtool source 5896 tree, `/home/src/libtool/libtool' is a libtool script that has been 5897 configured for your platform, and `~/bin' is a directory in your 5898 PATH: 5899 5900 trick$ cd ~/bin 5901 trick$ sed 's%^\(macro_version=\).*$%\1@VERSION@%; 5902 s%^\(macro_revision=\).*$%\1@package_revision@%; 5903 /^# ltmain\.sh/q' /home/src/libtool/libtool > libtool 5904 trick$ echo '. /home/src/libtool/ltmain.in' >> libtool 5905 trick$ chmod +x libtool 5906 trick$ libtool --version 5907 ltmain.sh (GNU @PACKAGE@@TIMESTAMP@) @VERSION@ 5908 5909 Copyright (C) 2009 Free Software Foundation, Inc. 5910 This is free software; see the source for copying conditions. There is NO 5911 warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. 5912 trick$ 5913 5914 The output of the final `libtool --version' command shows that the 5915`ltmain.in' script is being used directly. Now, modify `~/bin/libtool' 5916or `/home/src/libtool/ltmain.in' directly in order to test new changes 5917without having to rerun `configure'. 5918 5919 5920File: libtool.info, Node: GNU Free Documentation License, Next: Index, Prev: Maintaining, Up: Top 5921 5922Appendix A GNU Free Documentation License 5923***************************************** 5924 5925 Version 1.3, 3 November 2008 5926 5927 Copyright (C) 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc. 5928 `http://fsf.org/' 5929 5930 Everyone is permitted to copy and distribute verbatim copies 5931 of this license document, but changing it is not allowed. 5932 5933 0. PREAMBLE 5934 5935 The purpose of this License is to make a manual, textbook, or other 5936 functional and useful document "free" in the sense of freedom: to 5937 assure everyone the effective freedom to copy and redistribute it, 5938 with or without modifying it, either commercially or 5939 noncommercially. Secondarily, this License preserves for the 5940 author and publisher a way to get credit for their work, while not 5941 being considered responsible for modifications made by others. 5942 5943 This License is a kind of "copyleft", which means that derivative 5944 works of the document must themselves be free in the same sense. 5945 It complements the GNU General Public License, which is a copyleft 5946 license designed for free software. 5947 5948 We have designed this License in order to use it for manuals for 5949 free software, because free software needs free documentation: a 5950 free program should come with manuals providing the same freedoms 5951 that the software does. But this License is not limited to 5952 software manuals; it can be used for any textual work, regardless 5953 of subject matter or whether it is published as a printed book. 5954 We recommend this License principally for works whose purpose is 5955 instruction or reference. 5956 5957 1. APPLICABILITY AND DEFINITIONS 5958 5959 This License applies to any manual or other work, in any medium, 5960 that contains a notice placed by the copyright holder saying it 5961 can be distributed under the terms of this License. Such a notice 5962 grants a world-wide, royalty-free license, unlimited in duration, 5963 to use that work under the conditions stated herein. The 5964 "Document", below, refers to any such manual or work. Any member 5965 of the public is a licensee, and is addressed as "you". You 5966 accept the license if you copy, modify or distribute the work in a 5967 way requiring permission under copyright law. 5968 5969 A "Modified Version" of the Document means any work containing the 5970 Document or a portion of it, either copied verbatim, or with 5971 modifications and/or translated into another language. 5972 5973 A "Secondary Section" is a named appendix or a front-matter section 5974 of the Document that deals exclusively with the relationship of the 5975 publishers or authors of the Document to the Document's overall 5976 subject (or to related matters) and contains nothing that could 5977 fall directly within that overall subject. (Thus, if the Document 5978 is in part a textbook of mathematics, a Secondary Section may not 5979 explain any mathematics.) The relationship could be a matter of 5980 historical connection with the subject or with related matters, or 5981 of legal, commercial, philosophical, ethical or political position 5982 regarding them. 5983 5984 The "Invariant Sections" are certain Secondary Sections whose 5985 titles are designated, as being those of Invariant Sections, in 5986 the notice that says that the Document is released under this 5987 License. If a section does not fit the above definition of 5988 Secondary then it is not allowed to be designated as Invariant. 5989 The Document may contain zero Invariant Sections. If the Document 5990 does not identify any Invariant Sections then there are none. 5991 5992 The "Cover Texts" are certain short passages of text that are 5993 listed, as Front-Cover Texts or Back-Cover Texts, in the notice 5994 that says that the Document is released under this License. A 5995 Front-Cover Text may be at most 5 words, and a Back-Cover Text may 5996 be at most 25 words. 5997 5998 A "Transparent" copy of the Document means a machine-readable copy, 5999 represented in a format whose specification is available to the 6000 general public, that is suitable for revising the document 6001 straightforwardly with generic text editors or (for images 6002 composed of pixels) generic paint programs or (for drawings) some 6003 widely available drawing editor, and that is suitable for input to 6004 text formatters or for automatic translation to a variety of 6005 formats suitable for input to text formatters. A copy made in an 6006 otherwise Transparent file format whose markup, or absence of 6007 markup, has been arranged to thwart or discourage subsequent 6008 modification by readers is not Transparent. An image format is 6009 not Transparent if used for any substantial amount of text. A 6010 copy that is not "Transparent" is called "Opaque". 6011 6012 Examples of suitable formats for Transparent copies include plain 6013 ASCII without markup, Texinfo input format, LaTeX input format, 6014 SGML or XML using a publicly available DTD, and 6015 standard-conforming simple HTML, PostScript or PDF designed for 6016 human modification. Examples of transparent image formats include 6017 PNG, XCF and JPG. Opaque formats include proprietary formats that 6018 can be read and edited only by proprietary word processors, SGML or 6019 XML for which the DTD and/or processing tools are not generally 6020 available, and the machine-generated HTML, PostScript or PDF 6021 produced by some word processors for output purposes only. 6022 6023 The "Title Page" means, for a printed book, the title page itself, 6024 plus such following pages as are needed to hold, legibly, the 6025 material this License requires to appear in the title page. For 6026 works in formats which do not have any title page as such, "Title 6027 Page" means the text near the most prominent appearance of the 6028 work's title, preceding the beginning of the body of the text. 6029 6030 The "publisher" means any person or entity that distributes copies 6031 of the Document to the public. 6032 6033 A section "Entitled XYZ" means a named subunit of the Document 6034 whose title either is precisely XYZ or contains XYZ in parentheses 6035 following text that translates XYZ in another language. (Here XYZ 6036 stands for a specific section name mentioned below, such as 6037 "Acknowledgements", "Dedications", "Endorsements", or "History".) 6038 To "Preserve the Title" of such a section when you modify the 6039 Document means that it remains a section "Entitled XYZ" according 6040 to this definition. 6041 6042 The Document may include Warranty Disclaimers next to the notice 6043 which states that this License applies to the Document. These 6044 Warranty Disclaimers are considered to be included by reference in 6045 this License, but only as regards disclaiming warranties: any other 6046 implication that these Warranty Disclaimers may have is void and 6047 has no effect on the meaning of this License. 6048 6049 2. VERBATIM COPYING 6050 6051 You may copy and distribute the Document in any medium, either 6052 commercially or noncommercially, provided that this License, the 6053 copyright notices, and the license notice saying this License 6054 applies to the Document are reproduced in all copies, and that you 6055 add no other conditions whatsoever to those of this License. You 6056 may not use technical measures to obstruct or control the reading 6057 or further copying of the copies you make or distribute. However, 6058 you may accept compensation in exchange for copies. If you 6059 distribute a large enough number of copies you must also follow 6060 the conditions in section 3. 6061 6062 You may also lend copies, under the same conditions stated above, 6063 and you may publicly display copies. 6064 6065 3. COPYING IN QUANTITY 6066 6067 If you publish printed copies (or copies in media that commonly 6068 have printed covers) of the Document, numbering more than 100, and 6069 the Document's license notice requires Cover Texts, you must 6070 enclose the copies in covers that carry, clearly and legibly, all 6071 these Cover Texts: Front-Cover Texts on the front cover, and 6072 Back-Cover Texts on the back cover. Both covers must also clearly 6073 and legibly identify you as the publisher of these copies. The 6074 front cover must present the full title with all words of the 6075 title equally prominent and visible. You may add other material 6076 on the covers in addition. Copying with changes limited to the 6077 covers, as long as they preserve the title of the Document and 6078 satisfy these conditions, can be treated as verbatim copying in 6079 other respects. 6080 6081 If the required texts for either cover are too voluminous to fit 6082 legibly, you should put the first ones listed (as many as fit 6083 reasonably) on the actual cover, and continue the rest onto 6084 adjacent pages. 6085 6086 If you publish or distribute Opaque copies of the Document 6087 numbering more than 100, you must either include a 6088 machine-readable Transparent copy along with each Opaque copy, or 6089 state in or with each Opaque copy a computer-network location from 6090 which the general network-using public has access to download 6091 using public-standard network protocols a complete Transparent 6092 copy of the Document, free of added material. If you use the 6093 latter option, you must take reasonably prudent steps, when you 6094 begin distribution of Opaque copies in quantity, to ensure that 6095 this Transparent copy will remain thus accessible at the stated 6096 location until at least one year after the last time you 6097 distribute an Opaque copy (directly or through your agents or 6098 retailers) of that edition to the public. 6099 6100 It is requested, but not required, that you contact the authors of 6101 the Document well before redistributing any large number of 6102 copies, to give them a chance to provide you with an updated 6103 version of the Document. 6104 6105 4. MODIFICATIONS 6106 6107 You may copy and distribute a Modified Version of the Document 6108 under the conditions of sections 2 and 3 above, provided that you 6109 release the Modified Version under precisely this License, with 6110 the Modified Version filling the role of the Document, thus 6111 licensing distribution and modification of the Modified Version to 6112 whoever possesses a copy of it. In addition, you must do these 6113 things in the Modified Version: 6114 6115 A. Use in the Title Page (and on the covers, if any) a title 6116 distinct from that of the Document, and from those of 6117 previous versions (which should, if there were any, be listed 6118 in the History section of the Document). You may use the 6119 same title as a previous version if the original publisher of 6120 that version gives permission. 6121 6122 B. List on the Title Page, as authors, one or more persons or 6123 entities responsible for authorship of the modifications in 6124 the Modified Version, together with at least five of the 6125 principal authors of the Document (all of its principal 6126 authors, if it has fewer than five), unless they release you 6127 from this requirement. 6128 6129 C. State on the Title page the name of the publisher of the 6130 Modified Version, as the publisher. 6131 6132 D. Preserve all the copyright notices of the Document. 6133 6134 E. Add an appropriate copyright notice for your modifications 6135 adjacent to the other copyright notices. 6136 6137 F. Include, immediately after the copyright notices, a license 6138 notice giving the public permission to use the Modified 6139 Version under the terms of this License, in the form shown in 6140 the Addendum below. 6141 6142 G. Preserve in that license notice the full lists of Invariant 6143 Sections and required Cover Texts given in the Document's 6144 license notice. 6145 6146 H. Include an unaltered copy of this License. 6147 6148 I. Preserve the section Entitled "History", Preserve its Title, 6149 and add to it an item stating at least the title, year, new 6150 authors, and publisher of the Modified Version as given on 6151 the Title Page. If there is no section Entitled "History" in 6152 the Document, create one stating the title, year, authors, 6153 and publisher of the Document as given on its Title Page, 6154 then add an item describing the Modified Version as stated in 6155 the previous sentence. 6156 6157 J. Preserve the network location, if any, given in the Document 6158 for public access to a Transparent copy of the Document, and 6159 likewise the network locations given in the Document for 6160 previous versions it was based on. These may be placed in 6161 the "History" section. You may omit a network location for a 6162 work that was published at least four years before the 6163 Document itself, or if the original publisher of the version 6164 it refers to gives permission. 6165 6166 K. For any section Entitled "Acknowledgements" or "Dedications", 6167 Preserve the Title of the section, and preserve in the 6168 section all the substance and tone of each of the contributor 6169 acknowledgements and/or dedications given therein. 6170 6171 L. Preserve all the Invariant Sections of the Document, 6172 unaltered in their text and in their titles. Section numbers 6173 or the equivalent are not considered part of the section 6174 titles. 6175 6176 M. Delete any section Entitled "Endorsements". Such a section 6177 may not be included in the Modified Version. 6178 6179 N. Do not retitle any existing section to be Entitled 6180 "Endorsements" or to conflict in title with any Invariant 6181 Section. 6182 6183 O. Preserve any Warranty Disclaimers. 6184 6185 If the Modified Version includes new front-matter sections or 6186 appendices that qualify as Secondary Sections and contain no 6187 material copied from the Document, you may at your option 6188 designate some or all of these sections as invariant. To do this, 6189 add their titles to the list of Invariant Sections in the Modified 6190 Version's license notice. These titles must be distinct from any 6191 other section titles. 6192 6193 You may add a section Entitled "Endorsements", provided it contains 6194 nothing but endorsements of your Modified Version by various 6195 parties--for example, statements of peer review or that the text 6196 has been approved by an organization as the authoritative 6197 definition of a standard. 6198 6199 You may add a passage of up to five words as a Front-Cover Text, 6200 and a passage of up to 25 words as a Back-Cover Text, to the end 6201 of the list of Cover Texts in the Modified Version. Only one 6202 passage of Front-Cover Text and one of Back-Cover Text may be 6203 added by (or through arrangements made by) any one entity. If the 6204 Document already includes a cover text for the same cover, 6205 previously added by you or by arrangement made by the same entity 6206 you are acting on behalf of, you may not add another; but you may 6207 replace the old one, on explicit permission from the previous 6208 publisher that added the old one. 6209 6210 The author(s) and publisher(s) of the Document do not by this 6211 License give permission to use their names for publicity for or to 6212 assert or imply endorsement of any Modified Version. 6213 6214 5. COMBINING DOCUMENTS 6215 6216 You may combine the Document with other documents released under 6217 this License, under the terms defined in section 4 above for 6218 modified versions, provided that you include in the combination 6219 all of the Invariant Sections of all of the original documents, 6220 unmodified, and list them all as Invariant Sections of your 6221 combined work in its license notice, and that you preserve all 6222 their Warranty Disclaimers. 6223 6224 The combined work need only contain one copy of this License, and 6225 multiple identical Invariant Sections may be replaced with a single 6226 copy. If there are multiple Invariant Sections with the same name 6227 but different contents, make the title of each such section unique 6228 by adding at the end of it, in parentheses, the name of the 6229 original author or publisher of that section if known, or else a 6230 unique number. Make the same adjustment to the section titles in 6231 the list of Invariant Sections in the license notice of the 6232 combined work. 6233 6234 In the combination, you must combine any sections Entitled 6235 "History" in the various original documents, forming one section 6236 Entitled "History"; likewise combine any sections Entitled 6237 "Acknowledgements", and any sections Entitled "Dedications". You 6238 must delete all sections Entitled "Endorsements." 6239 6240 6. COLLECTIONS OF DOCUMENTS 6241 6242 You may make a collection consisting of the Document and other 6243 documents released under this License, and replace the individual 6244 copies of this License in the various documents with a single copy 6245 that is included in the collection, provided that you follow the 6246 rules of this License for verbatim copying of each of the 6247 documents in all other respects. 6248 6249 You may extract a single document from such a collection, and 6250 distribute it individually under this License, provided you insert 6251 a copy of this License into the extracted document, and follow 6252 this License in all other respects regarding verbatim copying of 6253 that document. 6254 6255 7. AGGREGATION WITH INDEPENDENT WORKS 6256 6257 A compilation of the Document or its derivatives with other 6258 separate and independent documents or works, in or on a volume of 6259 a storage or distribution medium, is called an "aggregate" if the 6260 copyright resulting from the compilation is not used to limit the 6261 legal rights of the compilation's users beyond what the individual 6262 works permit. When the Document is included in an aggregate, this 6263 License does not apply to the other works in the aggregate which 6264 are not themselves derivative works of the Document. 6265 6266 If the Cover Text requirement of section 3 is applicable to these 6267 copies of the Document, then if the Document is less than one half 6268 of the entire aggregate, the Document's Cover Texts may be placed 6269 on covers that bracket the Document within the aggregate, or the 6270 electronic equivalent of covers if the Document is in electronic 6271 form. Otherwise they must appear on printed covers that bracket 6272 the whole aggregate. 6273 6274 8. TRANSLATION 6275 6276 Translation is considered a kind of modification, so you may 6277 distribute translations of the Document under the terms of section 6278 4. Replacing Invariant Sections with translations requires special 6279 permission from their copyright holders, but you may include 6280 translations of some or all Invariant Sections in addition to the 6281 original versions of these Invariant Sections. You may include a 6282 translation of this License, and all the license notices in the 6283 Document, and any Warranty Disclaimers, provided that you also 6284 include the original English version of this License and the 6285 original versions of those notices and disclaimers. In case of a 6286 disagreement between the translation and the original version of 6287 this License or a notice or disclaimer, the original version will 6288 prevail. 6289 6290 If a section in the Document is Entitled "Acknowledgements", 6291 "Dedications", or "History", the requirement (section 4) to 6292 Preserve its Title (section 1) will typically require changing the 6293 actual title. 6294 6295 9. TERMINATION 6296 6297 You may not copy, modify, sublicense, or distribute the Document 6298 except as expressly provided under this License. Any attempt 6299 otherwise to copy, modify, sublicense, or distribute it is void, 6300 and will automatically terminate your rights under this License. 6301 6302 However, if you cease all violation of this License, then your 6303 license from a particular copyright holder is reinstated (a) 6304 provisionally, unless and until the copyright holder explicitly 6305 and finally terminates your license, and (b) permanently, if the 6306 copyright holder fails to notify you of the violation by some 6307 reasonable means prior to 60 days after the cessation. 6308 6309 Moreover, your license from a particular copyright holder is 6310 reinstated permanently if the copyright holder notifies you of the 6311 violation by some reasonable means, this is the first time you have 6312 received notice of violation of this License (for any work) from 6313 that copyright holder, and you cure the violation prior to 30 days 6314 after your receipt of the notice. 6315 6316 Termination of your rights under this section does not terminate 6317 the licenses of parties who have received copies or rights from 6318 you under this License. If your rights have been terminated and 6319 not permanently reinstated, receipt of a copy of some or all of 6320 the same material does not give you any rights to use it. 6321 6322 10. FUTURE REVISIONS OF THIS LICENSE 6323 6324 The Free Software Foundation may publish new, revised versions of 6325 the GNU Free Documentation License from time to time. Such new 6326 versions will be similar in spirit to the present version, but may 6327 differ in detail to address new problems or concerns. See 6328 `http://www.gnu.org/copyleft/'. 6329 6330 Each version of the License is given a distinguishing version 6331 number. If the Document specifies that a particular numbered 6332 version of this License "or any later version" applies to it, you 6333 have the option of following the terms and conditions either of 6334 that specified version or of any later version that has been 6335 published (not as a draft) by the Free Software Foundation. If 6336 the Document does not specify a version number of this License, 6337 you may choose any version ever published (not as a draft) by the 6338 Free Software Foundation. If the Document specifies that a proxy 6339 can decide which future versions of this License can be used, that 6340 proxy's public statement of acceptance of a version permanently 6341 authorizes you to choose that version for the Document. 6342 6343 11. RELICENSING 6344 6345 "Massive Multiauthor Collaboration Site" (or "MMC Site") means any 6346 World Wide Web server that publishes copyrightable works and also 6347 provides prominent facilities for anybody to edit those works. A 6348 public wiki that anybody can edit is an example of such a server. 6349 A "Massive Multiauthor Collaboration" (or "MMC") contained in the 6350 site means any set of copyrightable works thus published on the MMC 6351 site. 6352 6353 "CC-BY-SA" means the Creative Commons Attribution-Share Alike 3.0 6354 license published by Creative Commons Corporation, a not-for-profit 6355 corporation with a principal place of business in San Francisco, 6356 California, as well as future copyleft versions of that license 6357 published by that same organization. 6358 6359 "Incorporate" means to publish or republish a Document, in whole or 6360 in part, as part of another Document. 6361 6362 An MMC is "eligible for relicensing" if it is licensed under this 6363 License, and if all works that were first published under this 6364 License somewhere other than this MMC, and subsequently 6365 incorporated in whole or in part into the MMC, (1) had no cover 6366 texts or invariant sections, and (2) were thus incorporated prior 6367 to November 1, 2008. 6368 6369 The operator of an MMC Site may republish an MMC contained in the 6370 site under CC-BY-SA on the same site at any time before August 1, 6371 2009, provided the MMC is eligible for relicensing. 6372 6373 6374ADDENDUM: How to use this License for your documents 6375==================================================== 6376 6377To use this License in a document you have written, include a copy of 6378the License in the document and put the following copyright and license 6379notices just after the title page: 6380 6381 Copyright (C) YEAR YOUR NAME. 6382 Permission is granted to copy, distribute and/or modify this document 6383 under the terms of the GNU Free Documentation License, Version 1.3 6384 or any later version published by the Free Software Foundation; 6385 with no Invariant Sections, no Front-Cover Texts, and no Back-Cover 6386 Texts. A copy of the license is included in the section entitled ``GNU 6387 Free Documentation License''. 6388 6389 If you have Invariant Sections, Front-Cover Texts and Back-Cover 6390Texts, replace the "with...Texts." line with this: 6391 6392 with the Invariant Sections being LIST THEIR TITLES, with 6393 the Front-Cover Texts being LIST, and with the Back-Cover Texts 6394 being LIST. 6395 6396 If you have Invariant Sections without Cover Texts, or some other 6397combination of the three, merge those two alternatives to suit the 6398situation. 6399 6400 If your document contains nontrivial examples of program code, we 6401recommend releasing these examples in parallel under your choice of 6402free software license, such as the GNU General Public License, to 6403permit their use in free software. 6404 6405