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