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