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