| This is doc/libtool.info, produced by makeinfo version 4.13 from |
| ./doc/libtool.texi. |
| |
| INFO-DIR-SECTION GNU programming tools |
| START-INFO-DIR-ENTRY |
| * Libtool: (libtool). Generic shared library support script. |
| END-INFO-DIR-ENTRY |
| |
| INFO-DIR-SECTION Individual utilities |
| START-INFO-DIR-ENTRY |
| * libtool-invocation: (libtool)Invoking libtool. |
| Running the `libtool' script. |
| * libtoolize: (libtool)Invoking libtoolize. Adding libtool support. |
| END-INFO-DIR-ENTRY |
| |
| This file documents GNU Libtool 2.4.2 |
| |
| Copyright (C) 1996-2011 Free Software Foundation, Inc. |
| |
| Permission is granted to copy, distribute and/or modify this document |
| under the terms of the GNU Free Documentation License, Version 1.3 or |
| any later version published by the Free Software Foundation; with no |
| Invariant Sections, with no Front-Cover Texts, and with no Back-Cover |
| Texts. A copy of the license is included in the section entitled "GNU |
| Free Documentation License". |
| |
| |
| File: libtool.info, Node: Top, Next: Introduction, Prev: (dir), Up: (dir) |
| |
| Shared library support for GNU |
| ****************************** |
| |
| This file documents GNU Libtool, a script that allows package developers |
| to provide generic shared library support. This edition documents |
| version 2.4.2. |
| |
| *Note Reporting bugs::, for information on how to report problems |
| with GNU Libtool. |
| |
| * Menu: |
| |
| * Introduction:: What the heck is libtool? |
| * Libtool paradigm:: How libtool's view of libraries is different. |
| * Using libtool:: Example of using libtool to build libraries. |
| * Invoking libtool:: Running the `libtool' script. |
| * Integrating libtool:: Using libtool in your own packages. |
| * Other languages:: Using libtool without a C compiler. |
| * Versioning:: Using library interface versions. |
| * Library tips:: Tips for library interface design. |
| * Inter-library dependencies:: Libraries that depend on other libraries. |
| * Dlopened modules:: `dlopen'ing libtool-created libraries. |
| * Using libltdl:: Libtool's portable `dlopen' wrapper library. |
| * Trace interface:: Libtool's trace interface. |
| * FAQ:: Frequently Asked Questions |
| * Troubleshooting:: When libtool doesn't work as advertised. |
| * Maintaining:: Information used by the libtool maintainer. |
| * GNU Free Documentation License:: License for this manual. |
| * Combined Index:: Full index. |
| |
| --- The Detailed Node Listing --- |
| |
| Introduction |
| |
| * Motivation:: Why does GNU need a libtool? |
| * Issues:: The problems that need to be addressed. |
| * Other implementations:: How other people have solved these issues. |
| * Postmortem:: Learning from past difficulties. |
| |
| Using libtool |
| |
| * Creating object files:: Compiling object files for libraries. |
| * Linking libraries:: Creating libraries from object files. |
| * Linking executables:: Linking object files against libtool libraries. |
| * Debugging executables:: Running GDB on libtool-generated programs. |
| * Installing libraries:: Making libraries available to users. |
| * Installing executables:: Making programs available to users. |
| * Static libraries:: When shared libraries are not wanted. |
| |
| Linking executables |
| |
| * Wrapper executables:: Wrapper executables for some platforms. |
| |
| Invoking `libtool' |
| |
| * Compile mode:: Creating library object files. |
| * Link mode:: Generating executables and libraries. |
| * Execute mode:: Debugging libtool-generated programs. |
| * Install mode:: Making libraries and executables public. |
| * Finish mode:: Completing a library installation. |
| * Uninstall mode:: Removing installed executables and libraries. |
| * Clean mode:: Removing uninstalled executables and libraries. |
| |
| Integrating libtool with your package |
| |
| * Autoconf macros:: Autoconf macros exported by libtool. |
| * Makefile rules:: Writing `Makefile' rules for libtool. |
| * Using Automake:: Automatically supporting libtool. |
| * Configuring:: Configuring libtool for a host system. |
| * Distributing:: What files to distribute with your package. |
| * Static-only libraries:: Sometimes shared libraries are just a pain. |
| |
| Configuring libtool |
| |
| * LT_INIT:: Configuring `libtool' in `configure.ac'. |
| * Configure notes:: Platform-specific notes for configuration. |
| |
| Including libtool in your package |
| |
| * Invoking libtoolize:: `libtoolize' command line options. |
| * Autoconf and LTLIBOBJS:: Autoconf automates LTLIBOBJS generation. |
| |
| Using libtool with other languages |
| |
| * C++ libraries:: Writing libraries for C++ |
| * Tags:: Tags |
| |
| Library interface versions |
| |
| * Interfaces:: What are library interfaces? |
| * Libtool versioning:: Libtool's versioning system. |
| * Updating version info:: Changing version information before releases. |
| * Release numbers:: Breaking binary compatibility for aesthetics. |
| |
| Tips for interface design |
| |
| * C header files:: How to write portable include files. |
| |
| Dlopened modules |
| |
| * Building modules:: Creating dlopenable objects and libraries. |
| * Dlpreopening:: Dlopening that works on static platforms. |
| * Linking with dlopened modules:: Using dlopenable modules in libraries. |
| * Finding the dlname:: Choosing the right file to `dlopen'. |
| * Dlopen issues:: Unresolved problems that need your attention. |
| |
| Using libltdl |
| |
| * Libltdl interface:: How to use libltdl in your programs. |
| * Modules for libltdl:: Creating modules that can be `dlopen'ed. |
| * Thread Safety in libltdl:: Registering callbacks for multi-thread safety. |
| * User defined module data:: Associating data with loaded modules. |
| * Module loaders for libltdl:: Creating user defined module loaders. |
| * Distributing libltdl:: How to distribute libltdl with your package. |
| |
| Frequently Asked Questions about libtool |
| |
| * Stripped link flags:: Dropped flags when creating a library |
| |
| Troubleshooting |
| |
| * Libtool test suite:: Libtool's self-tests. |
| * Reporting bugs:: How to report problems with libtool. |
| |
| The libtool test suite |
| |
| * Test descriptions:: The contents of the old test suite. |
| * When tests fail:: What to do when a test fails. |
| |
| Maintenance notes for libtool |
| |
| * New ports:: How to port libtool to new systems. |
| * Tested platforms:: When libtool was last tested. |
| * Platform quirks:: Information about different library systems. |
| * libtool script contents:: Configuration information that libtool uses. |
| * Cheap tricks:: Making libtool maintainership easier. |
| |
| Porting libtool to new systems |
| |
| * Information sources:: Where to find relevant documentation |
| * Porting inter-library dependencies:: Implementation details explained |
| |
| Platform quirks |
| |
| * References:: Finding more information. |
| * Compilers:: Creating object files from source files. |
| * Reloadable objects:: Binding object files together. |
| * Multiple dependencies:: Removing duplicate dependent libraries. |
| * Archivers:: Programs that create static archives. |
| * Cross compiling:: Issues that arise when cross compiling. |
| * File name conversion:: Converting file names between platforms. |
| * Windows DLLs:: Windows header defines. |
| |
| File name conversion |
| |
| * File Name Conversion Failure:: What happens when file name conversion fails |
| * Native MinGW File Name Conversion:: MSYS file name conversion idiosyncrasies |
| * Cygwin/Windows File Name Conversion:: Using `cygpath' to convert Cygwin file names |
| * Unix/Windows File Name Conversion:: Using Wine to convert Unix paths |
| * LT_CYGPATH:: Invoking `cygpath' from other environments |
| * Cygwin to MinGW Cross:: Other notes concerning MinGW cross |
| |
| |
| File: libtool.info, Node: Introduction, Next: Libtool paradigm, Prev: Top, Up: Top |
| |
| 1 Introduction |
| ************** |
| |
| In the past, if you were a source code package developer and wanted to |
| take advantage of the power of shared libraries, you needed to write |
| custom support code for each platform on which your package ran. You |
| also had to design a configuration interface so that the package |
| installer could choose what sort of libraries were built. |
| |
| GNU Libtool simplifies your job by encapsulating both the |
| platform-specific dependencies, and the user interface, in a single |
| script. GNU Libtool is designed so that the complete functionality of |
| each host type is available via a generic interface, but nasty quirks |
| are hidden from the programmer. |
| |
| GNU Libtool's consistent interface is reassuring... users don't need |
| to read obscure documentation in order to have their favorite source |
| package build shared libraries. They just run your package `configure' |
| script (or equivalent), and libtool does all the dirty work. |
| |
| There are several examples throughout this document. All assume the |
| same environment: we want to build a library, `libhello', in a generic |
| way. |
| |
| `libhello' could be a shared library, a static library, or both... |
| whatever is available on the host system, as long as libtool has been |
| ported to it. |
| |
| This chapter explains the original design philosophy of libtool. |
| Feel free to skip to the next chapter, unless you are interested in |
| history, or want to write code to extend libtool in a consistent way. |
| |
| * Menu: |
| |
| * Motivation:: Why does GNU need a libtool? |
| * Issues:: The problems that need to be addressed. |
| * Other implementations:: How other people have solved these issues. |
| * Postmortem:: Learning from past difficulties. |
| |
| |
| File: libtool.info, Node: Motivation, Next: Issues, Up: Introduction |
| |
| 1.1 Motivation for writing libtool |
| ================================== |
| |
| Since early 1995, several different GNU developers have recognized the |
| importance of having shared library support for their packages. The |
| primary motivation for such a change is to encourage modularity and |
| reuse of code (both conceptually and physically) in GNU programs. |
| |
| Such a demand means that the way libraries are built in GNU packages |
| needs to be general, to allow for any library type the package installer |
| might want. The problem is compounded by the absence of a standard |
| procedure for creating shared libraries on different platforms. |
| |
| The following sections outline the major issues facing shared library |
| support in GNU, and how shared library support could be standardized |
| with libtool. |
| |
| The following specifications were used in developing and evaluating |
| this system: |
| |
| 1. The system must be as elegant as possible. |
| |
| 2. The system must be fully integrated with the GNU Autoconf and |
| Automake utilities, so that it will be easy for GNU maintainers to |
| use. However, the system must not require these tools, so that it |
| can be used by non-GNU packages. |
| |
| 3. Portability to other (non-GNU) architectures and tools is |
| desirable. |
| |
| |
| File: libtool.info, Node: Issues, Next: Other implementations, Prev: Motivation, Up: Introduction |
| |
| 1.2 Implementation issues |
| ========================= |
| |
| The following issues need to be addressed in any reusable shared library |
| system, specifically libtool: |
| |
| 1. The package installer should be able to control what sort of |
| libraries are built. |
| |
| 2. It can be tricky to run dynamically linked programs whose |
| libraries have not yet been installed. `LD_LIBRARY_PATH' must be |
| set properly (if it is supported), or programs fail to run. |
| |
| 3. The system must operate consistently even on hosts that don't |
| support shared libraries. |
| |
| 4. The commands required to build shared libraries may differ wildly |
| from host to host. These need to be determined at configure time |
| in a consistent way. |
| |
| 5. It is not always obvious with what prefix or suffix a shared |
| library should be installed. This makes it difficult for |
| `Makefile' rules, since they generally assume that file names are |
| the same from host to host. |
| |
| 6. The system needs a simple library version number abstraction, so |
| that shared libraries can be upgraded in place. The programmer |
| should be informed how to design the interfaces to the library to |
| maximize binary compatibility. |
| |
| 7. The install `Makefile' target should warn the package installer to |
| set the proper environment variables (`LD_LIBRARY_PATH' or |
| equivalent), or run `ldconfig'. |
| |
| |
| File: libtool.info, Node: Other implementations, Next: Postmortem, Prev: Issues, Up: Introduction |
| |
| 1.3 Other implementations |
| ========================= |
| |
| Even before libtool was developed, many free software packages built and |
| installed their own shared libraries. At first, these packages were |
| examined to avoid reinventing existing features. |
| |
| Now it is clear that none of these packages have documented the |
| details of shared library systems that libtool requires. So, other |
| packages have been more or less abandoned as influences. |
| |
| |
| File: libtool.info, Node: Postmortem, Prev: Other implementations, Up: Introduction |
| |
| 1.4 A postmortem analysis of other implementations |
| ================================================== |
| |
| In all fairness, each of the implementations that were examined do the |
| job that they were intended to do, for a number of different host |
| systems. However, none of these solutions seem to function well as a |
| generalized, reusable component. |
| |
| Most were too complex to use (much less modify) without understanding |
| exactly what the implementation does, and they were generally not |
| documented. |
| |
| The main difficulty is that different vendors have different views of |
| what libraries are, and none of the packages that were examined seemed |
| to be confident enough to settle on a single paradigm that just _works_. |
| |
| Ideally, libtool would be a standard that would be implemented as |
| series of extensions and modifications to existing library systems to |
| make them work consistently. However, it is not an easy task to |
| convince operating system developers to mend their evil ways, and |
| people want to build shared libraries right now, even on buggy, broken, |
| confused operating systems. |
| |
| For this reason, libtool was designed as an independent shell script. |
| It isolates the problems and inconsistencies in library building that |
| plague `Makefile' writers by wrapping the compiler suite on different |
| platforms with a consistent, powerful interface. |
| |
| With luck, libtool will be useful to and used by the GNU community, |
| and that the lessons that were learned in writing it will be taken up by |
| designers of future library systems. |
| |
| |
| File: libtool.info, Node: Libtool paradigm, Next: Using libtool, Prev: Introduction, Up: Top |
| |
| 2 The libtool paradigm |
| ********************** |
| |
| At first, libtool was designed to support an arbitrary number of library |
| object types. After libtool was ported to more platforms, a new |
| paradigm gradually developed for describing the relationship between |
| libraries and programs. |
| |
| In summary, "libraries are programs with multiple entry points, and |
| more formally defined interfaces." |
| |
| Version 0.7 of libtool was a complete redesign and rewrite of |
| libtool to reflect this new paradigm. So far, it has proved to be |
| successful: libtool is simpler and more useful than before. |
| |
| The best way to introduce the libtool paradigm is to contrast it with |
| the paradigm of existing library systems, with examples from each. It |
| is a new way of thinking, so it may take a little time to absorb, but |
| when you understand it, the world becomes simpler. |
| |
| |
| File: libtool.info, Node: Using libtool, Next: Invoking libtool, Prev: Libtool paradigm, Up: Top |
| |
| 3 Using libtool |
| *************** |
| |
| It makes little sense to talk about using libtool in your own packages |
| until you have seen how it makes your life simpler. The examples in |
| this chapter introduce the main features of libtool by comparing the |
| standard library building procedure to libtool's operation on two |
| different platforms: |
| |
| `a23' |
| An Ultrix 4.2 platform with only static libraries. |
| |
| `burger' |
| A NetBSD/i386 1.2 platform with shared libraries. |
| |
| You can follow these examples on your own platform, using the |
| preconfigured libtool script that was installed with libtool (*note |
| Configuring::). |
| |
| Source files for the following examples are taken from the `demo' |
| subdirectory of the libtool distribution. Assume that we are building a |
| library, `libhello', out of the files `foo.c' and `hello.c'. |
| |
| Note that the `foo.c' source file uses the `cos' math library |
| function, which is usually found in the standalone math library, and not |
| the C library (*note Trigonometric Functions: (libc)Trig Functions.). |
| So, we need to add `-lm' to the end of the link line whenever we link |
| `foo.lo' into an executable or a library (*note Inter-library |
| dependencies::). |
| |
| The same rule applies whenever you use functions that don't appear in |
| the standard C library... you need to add the appropriate `-lNAME' flag |
| to the end of the link line when you link against those objects. |
| |
| After we have built that library, we want to create a program by |
| linking `main.o' against `libhello'. |
| |
| * Menu: |
| |
| * Creating object files:: Compiling object files for libraries. |
| * Linking libraries:: Creating libraries from object files. |
| * Linking executables:: Linking object files against libtool libraries. |
| * Debugging executables:: Running GDB on libtool-generated programs. |
| * Installing libraries:: Making libraries available to users. |
| * Installing executables:: Making programs available to users. |
| * Static libraries:: When shared libraries are not wanted. |
| |
| |
| File: libtool.info, Node: Creating object files, Next: Linking libraries, Up: Using libtool |
| |
| 3.1 Creating object files |
| ========================= |
| |
| To create an object file from a source file, the compiler is invoked |
| with the `-c' flag (and any other desired flags): |
| |
| burger$ gcc -g -O -c main.c |
| burger$ |
| |
| The above compiler command produces an object file, usually named |
| `main.o', from the source file `main.c'. |
| |
| For most library systems, creating object files that become part of a |
| static library is as simple as creating object files that are linked to |
| form an executable: |
| |
| burger$ gcc -g -O -c foo.c |
| burger$ gcc -g -O -c hello.c |
| burger$ |
| |
| Shared libraries, however, may only be built from |
| "position-independent code" (PIC). So, special flags must be passed to |
| the compiler to tell it to generate PIC rather than the standard |
| position-dependent code. |
| |
| Since this is a library implementation detail, libtool hides the |
| complexity of PIC compiler flags and uses separate library object files |
| (the PIC one lives in the `.libs' subdirectory and the static one lives |
| in the current directory). On systems without shared libraries, the |
| PIC library object files are not created, whereas on systems where all |
| code is PIC, such as AIX, the static ones are not created. |
| |
| To create library object files for `foo.c' and `hello.c', simply |
| invoke libtool with the standard compilation command as arguments |
| (*note Compile mode::): |
| |
| a23$ libtool --mode=compile gcc -g -O -c foo.c |
| gcc -g -O -c foo.c -o foo.o |
| a23$ libtool --mode=compile gcc -g -O -c hello.c |
| gcc -g -O -c hello.c -o hello.o |
| a23$ |
| |
| Note that libtool silently creates an additional control file on each |
| `compile' invocation. The `.lo' file is the libtool object, which |
| Libtool uses to determine what object file may be built into a shared |
| library. On `a23', only static libraries are supported so the library |
| objects look like this: |
| |
| # foo.lo - a libtool object file |
| # Generated by ltmain.sh (GNU libtool) 2.4.2 |
| # |
| # Please DO NOT delete this file! |
| # It is necessary for linking the library. |
| |
| # Name of the PIC object. |
| pic_object=none |
| |
| # Name of the non-PIC object. |
| non_pic_object='foo.o' |
| |
| On shared library systems, libtool automatically generates an |
| additional PIC object by inserting the appropriate PIC generation flags |
| into the compilation command: |
| |
| burger$ libtool --mode=compile gcc -g -O -c foo.c |
| mkdir .libs |
| gcc -g -O -c foo.c -fPIC -DPIC -o .libs/foo.o |
| gcc -g -O -c foo.c -o foo.o >/dev/null 2>&1 |
| burger$ |
| |
| Note that Libtool automatically created `.libs' directory upon its |
| first execution, where PIC library object files will be stored. |
| |
| Since `burger' supports shared libraries, and requires PIC objects |
| to build them, Libtool has compiled a PIC object this time, and made a |
| note of it in the libtool object: |
| |
| # foo.lo - a libtool object file |
| # Generated by ltmain.sh (GNU libtool) 2.4.2 |
| # |
| # Please DO NOT delete this file! |
| # It is necessary for linking the library. |
| |
| # Name of the PIC object. |
| pic_object='.libs/foo.o' |
| |
| # Name of the non-PIC object. |
| non_pic_object='foo.o' |
| |
| Notice that the second run of GCC has its output discarded. This is |
| done so that compiler warnings aren't annoyingly duplicated. If you |
| need to see both sets of warnings (you might have conditional code |
| inside `#ifdef PIC' for example), you can turn off suppression with the |
| `-no-suppress' option to libtool's compile mode: |
| |
| burger$ libtool --mode=compile gcc -no-suppress -g -O -c hello.c |
| gcc -g -O -c hello.c -fPIC -DPIC -o .libs/hello.o |
| gcc -g -O -c hello.c -o hello.o |
| burger$ |
| |
| |
| File: libtool.info, Node: Linking libraries, Next: Linking executables, Prev: Creating object files, Up: Using libtool |
| |
| 3.2 Linking libraries |
| ===================== |
| |
| Without libtool, the programmer would invoke the `ar' command to create |
| a static library: |
| |
| burger$ ar cru libhello.a hello.o foo.o |
| burger$ |
| |
| But of course, that would be too simple, so many systems require that |
| you run the `ranlib' command on the resulting library (to give it |
| better karma, or something): |
| |
| burger$ ranlib libhello.a |
| burger$ |
| |
| It seems more natural to use the C compiler for this task, given |
| libtool's "libraries are programs" approach. So, on platforms without |
| shared libraries, libtool simply acts as a wrapper for the system `ar' |
| (and possibly `ranlib') commands. |
| |
| Again, the libtool control file name (`.la' suffix) differs from the |
| standard library name (`.a' suffix). The arguments to libtool are the |
| same ones you would use to produce an executable named `libhello.la' |
| with your compiler (*note Link mode::): |
| |
| a23$ libtool --mode=link gcc -g -O -o libhello.la foo.o hello.o |
| *** Warning: Linking the shared library libhello.la against the |
| *** non-libtool objects foo.o hello.o is not portable! |
| ar cru .libs/libhello.a |
| ranlib .libs/libhello.a |
| creating libhello.la |
| (cd .libs && rm -f libhello.la && ln -s ../libhello.la libhello.la) |
| a23$ |
| |
| Aha! Libtool caught a common error... trying to build a library |
| from standard objects instead of special `.lo' object files. This |
| doesn't matter so much for static libraries, but on shared library |
| systems, it is of great importance. (Note that you may replace |
| `libhello.la' with `libhello.a' in which case libtool won't issue the |
| warning any more. But although this method works, this is not intended |
| to be used because it makes you lose the benefits of using Libtool.) |
| |
| So, let's try again, this time with the library object files. |
| Remember also that we need to add `-lm' to the link command line because |
| `foo.c' uses the `cos' math library function (*note Using libtool::). |
| |
| Another complication in building shared libraries is that we need to |
| specify the path to the directory in which they (eventually) will be |
| installed (in this case, `/usr/local/lib')(1): |
| |
| a23$ libtool --mode=link gcc -g -O -o libhello.la foo.lo hello.lo \ |
| -rpath /usr/local/lib -lm |
| ar cru .libs/libhello.a foo.o hello.o |
| ranlib .libs/libhello.a |
| creating libhello.la |
| (cd .libs && rm -f libhello.la && ln -s ../libhello.la libhello.la) |
| a23$ |
| |
| Now, let's try the same trick on the shared library platform: |
| |
| burger$ libtool --mode=link gcc -g -O -o libhello.la foo.lo hello.lo \ |
| -rpath /usr/local/lib -lm |
| rm -fr .libs/libhello.a .libs/libhello.la |
| ld -Bshareable -o .libs/libhello.so.0.0 .libs/foo.o .libs/hello.o -lm |
| ar cru .libs/libhello.a foo.o hello.o |
| ranlib .libs/libhello.a |
| creating libhello.la |
| (cd .libs && rm -f libhello.la && ln -s ../libhello.la libhello.la) |
| burger$ |
| |
| Now that's significantly cooler... Libtool just ran an obscure `ld' |
| command to create a shared library, as well as the static library. |
| |
| Note how libtool creates extra files in the `.libs' subdirectory, |
| rather than the current directory. This feature is to make it easier |
| to clean up the build directory, and to help ensure that other programs |
| fail horribly if you accidentally forget to use libtool when you should. |
| |
| Again, you may want to have a look at the `.la' file in order to see |
| what Libtool stores in it. In particular, you will see that Libtool |
| uses this file to remember the destination directory for the library |
| (the argument to `-rpath') as well as the dependency on the math |
| library (`-lm'). |
| |
| ---------- Footnotes ---------- |
| |
| (1) If you don't specify an `rpath', then libtool builds a libtool |
| convenience archive, not a shared library (*note Static libraries::). |
| |
| |
| File: libtool.info, Node: Linking executables, Next: Debugging executables, Prev: Linking libraries, Up: Using libtool |
| |
| 3.3 Linking executables |
| ======================= |
| |
| If you choose at this point to "install" the library (put it in a |
| permanent location) before linking executables against it, then you |
| don't need to use libtool to do the linking. Simply use the appropriate |
| `-L' and `-l' flags to specify the library's location. |
| |
| Some system linkers insist on encoding the full directory name of |
| each shared library in the resulting executable. Libtool has to work |
| around this misfeature by special magic to ensure that only permanent |
| directory names are put into installed executables. |
| |
| The importance of this bug must not be overlooked: it won't cause |
| programs to crash in obvious ways. It creates a security hole, and |
| possibly even worse, if you are modifying the library source code after |
| you have installed the package, you will change the behaviour of the |
| installed programs! |
| |
| So, if you want to link programs against the library before you |
| install it, you must use libtool to do the linking. |
| |
| Here's the old way of linking against an uninstalled library: |
| |
| burger$ gcc -g -O -o hell.old main.o libhello.a -lm |
| burger$ |
| |
| Libtool's way is almost the same(1) (*note Link mode::): |
| |
| a23$ libtool --mode=link gcc -g -O -o hell main.o libhello.la |
| gcc -g -O -o hell main.o ./.libs/libhello.a -lm |
| a23$ |
| |
| That looks too simple to be true. All libtool did was transform |
| `libhello.la' to `./.libs/libhello.a', but remember that `a23' has no |
| shared libraries. Notice that Libtool also remembered that |
| `libhello.la' depends on `-lm', so even though we didn't specify `-lm' |
| on the libtool command line(2) Libtool has added it to the `gcc' link |
| line for us. |
| |
| On `burger' Libtool links against the uninstalled shared library: |
| |
| burger$ libtool --mode=link gcc -g -O -o hell main.o libhello.la |
| gcc -g -O -o .libs/hell main.o -L./.libs -R/usr/local/lib -lhello -lm |
| creating hell |
| burger$ |
| |
| Now assume `libhello.la' had already been installed, and you want to |
| link a new program with it. You could figure out where it lives by |
| yourself, then run: |
| |
| burger$ gcc -g -O -o test test.o -L/usr/local/lib -lhello -lm |
| |
| However, unless `/usr/local/lib' is in the standard library search |
| path, you won't be able to run `test'. However, if you use libtool to |
| link the already-installed libtool library, it will do The Right Thing |
| (TM) for you: |
| |
| burger$ libtool --mode=link gcc -g -O -o test test.o \ |
| /usr/local/lib/libhello.la |
| gcc -g -O -o .libs/test test.o -Wl,--rpath \ |
| -Wl,/usr/local/lib /usr/local/lib/libhello.a -lm |
| creating test |
| burger$ |
| |
| Note that libtool added the necessary run-time path flag, as well as |
| `-lm', the library libhello.la depended upon. Nice, huh? |
| |
| Notice that the executable, `hell', was actually created in the |
| `.libs' subdirectory. Then, a wrapper script (or, on certain |
| platforms, a wrapper executable *note Wrapper executables::) was |
| created in the current directory. |
| |
| Since libtool created a wrapper script, you should use libtool to |
| install it and debug it too. However, since the program does not depend |
| on any uninstalled libtool library, it is probably usable even without |
| the wrapper script. |
| |
| On NetBSD 1.2, libtool encodes the installation directory of |
| `libhello', by using the `-R/usr/local/lib' compiler flag. Then, the |
| wrapper script guarantees that the executable finds the correct shared |
| library (the one in `./.libs') until it is properly installed. |
| |
| Let's compare the two different programs: |
| |
| burger$ time ./hell.old |
| Welcome to GNU Hell! |
| ** This is not GNU Hello. There is no built-in mail reader. ** |
| 0.21 real 0.02 user 0.08 sys |
| burger$ time ./hell |
| Welcome to GNU Hell! |
| ** This is not GNU Hello. There is no built-in mail reader. ** |
| 0.63 real 0.09 user 0.59 sys |
| burger$ |
| |
| The wrapper script takes significantly longer to execute, but at |
| least the results are correct, even though the shared library hasn't |
| been installed yet. |
| |
| So, what about all the space savings that shared libraries are |
| supposed to yield? |
| |
| burger$ ls -l hell.old libhello.a |
| -rwxr-xr-x 1 gord gord 15481 Nov 14 12:11 hell.old |
| -rw-r--r-- 1 gord gord 4274 Nov 13 18:02 libhello.a |
| burger$ ls -l .libs/hell .libs/libhello.* |
| -rwxr-xr-x 1 gord gord 11647 Nov 14 12:10 .libs/hell |
| -rw-r--r-- 1 gord gord 4274 Nov 13 18:44 .libs/libhello.a |
| -rwxr-xr-x 1 gord gord 12205 Nov 13 18:44 .libs/libhello.so.0.0 |
| burger$ |
| |
| Well, that sucks. Maybe I should just scrap this project and take up |
| basket weaving. |
| |
| Actually, it just proves an important point: shared libraries incur |
| overhead because of their (relative) complexity. In this situation, the |
| price of being dynamic is eight kilobytes, and the payoff is about four |
| kilobytes. So, having a shared `libhello' won't be an advantage until |
| we link it against at least a few more programs. |
| |
| * Menu: |
| |
| * Wrapper executables:: Wrapper executables for some platforms. |
| |
| ---------- Footnotes ---------- |
| |
| (1) However, you should avoid using `-L' or `-l' flags to link |
| against an uninstalled libtool library. Just specify the relative path |
| to the `.la' file, such as `../intl/libintl.la'. This is a design |
| decision to eliminate any ambiguity when linking against uninstalled |
| shared libraries. |
| |
| (2) And why should we? `main.o' doesn't directly depend on `-lm' |
| after all. |
| |
| |
| File: libtool.info, Node: Wrapper executables, Up: Linking executables |
| |
| 3.3.1 Wrapper executables for uninstalled programs |
| -------------------------------------------------- |
| |
| Some platforms, notably those hosted on Windows such as Cygwin and |
| MinGW, use a wrapper executable rather than a wrapper script to ensure |
| proper operation of uninstalled programs linked by libtool against |
| uninstalled shared libraries. The wrapper executable thus performs the |
| same function as the wrapper script used on other platforms, but allows |
| to satisfy the `make' rules for the program, whose name ends in |
| `$(EXEEXT)'. The actual program executable is created below .libs, and |
| its name will end in `$(EXEEXT)' and may or may not contain an `lt-' |
| prefix. This wrapper executable sets various environment values so |
| that the program executable may locate its (uninstalled) shared |
| libraries, and then launches the program executable. |
| |
| The wrapper executable provides a debug mode, enabled by passing the |
| command-line option `--lt-debug' (see below). When executing in debug |
| mode, diagnostic information will be printed to `stderr' before the |
| program executable is launched. |
| |
| Finally, the wrapper executable supports a number of command line |
| options that may be useful when debugging the operation of the wrapper |
| system. All of these options begin with `--lt-', and if present they |
| and their arguments will be removed from the argument list passed on to |
| the program executable. Therefore, the program executable may not |
| employ command line options that begin with `--lt-'. (In fact, the |
| wrapper executable will detect any command line options that begin with |
| `--lt-' and abort with an error message if the option is not |
| recognized). If this presents a problem, please contact the Libtool |
| team at the Libtool bug reporting address <bug-libtool@gnu.org>. |
| |
| These command line options include: |
| |
| `--lt-dump-script' |
| Causes the wrapper to print a copy of the wrapper _script_ to |
| `stdout', and exit. |
| |
| `--lt-debug' |
| Causes the wrapper to print diagnostic information to `stdout', |
| before launching the program executable. |
| |
| |
| For consistency, both the wrapper _script_ and the wrapper |
| _executable_ support these options. |
| |
| |
| File: libtool.info, Node: Debugging executables, Next: Installing libraries, Prev: Linking executables, Up: Using libtool |
| |
| 3.4 Debugging executables |
| ========================= |
| |
| If `hell' was a complicated program, you would certainly want to test |
| and debug it before installing it on your system. In the above |
| section, you saw how the libtool wrapper script makes it possible to run |
| the program directly, but unfortunately, this mechanism interferes with |
| the debugger: |
| |
| burger$ gdb hell |
| GDB is free software and you are welcome to distribute copies of it |
| under certain conditions; type "show copying" to see the conditions. |
| There is no warranty for GDB; type "show warranty" for details. |
| GDB 4.16 (i386-unknown-netbsd), (C) 1996 Free Software Foundation, Inc. |
| |
| "hell": not in executable format: File format not recognized |
| |
| (gdb) quit |
| burger$ |
| |
| Sad. It doesn't work because GDB doesn't know where the executable |
| lives. So, let's try again, by invoking GDB directly on the executable: |
| |
| burger$ gdb .libs/hell |
| GNU gdb 5.3 (i386-unknown-netbsd) |
| Copyright 2002 Free Software Foundation, Inc. |
| GDB is free software, covered by the GNU General Public License, |
| and you are welcome to change it and/or distribute copies of it |
| under certain conditions. Type "show copying" to see the conditions. |
| There is no warranty for GDB. Type "show warranty" for details. |
| (gdb) break main |
| Breakpoint 1 at 0x8048547: file main.c, line 29. |
| (gdb) run |
| Starting program: /home/src/libtool/demo/.libs/hell |
| /home/src/libtool/demo/.libs/hell: can't load library 'libhello.so.0' |
| |
| Program exited with code 020. |
| (gdb) quit |
| burger$ |
| |
| Argh. Now GDB complains because it cannot find the shared library |
| that `hell' is linked against. So, we must use libtool in order to |
| properly set the library path and run the debugger. Fortunately, we can |
| forget all about the `.libs' directory, and just run it on the |
| executable wrapper (*note Execute mode::): |
| |
| burger$ libtool --mode=execute gdb hell |
| GNU gdb 5.3 (i386-unknown-netbsd) |
| Copyright 2002 Free Software Foundation, Inc. |
| GDB is free software, covered by the GNU General Public License, |
| and you are welcome to change it and/or distribute copies of it |
| under certain conditions. Type "show copying" to see the conditions. |
| There is no warranty for GDB. Type "show warranty" for details. |
| (gdb) break main |
| Breakpoint 1 at 0x8048547: file main.c, line 29. |
| (gdb) run |
| Starting program: /home/src/libtool/demo/.libs/hell |
| |
| Breakpoint 1, main (argc=1, argv=0xbffffc40) at main.c:29 |
| 29 printf ("Welcome to GNU Hell!\n"); |
| (gdb) quit |
| The program is running. Quit anyway (and kill it)? (y or n) y |
| burger$ |
| |
| |
| File: libtool.info, Node: Installing libraries, Next: Installing executables, Prev: Debugging executables, Up: Using libtool |
| |
| 3.5 Installing libraries |
| ======================== |
| |
| Installing libraries on a non-libtool system is quite |
| straightforward... just copy them into place:(1) |
| |
| burger$ su |
| Password: ******** |
| burger# cp libhello.a /usr/local/lib/libhello.a |
| burger# |
| |
| Oops, don't forget the `ranlib' command: |
| |
| burger# ranlib /usr/local/lib/libhello.a |
| burger# |
| |
| Libtool installation is quite simple, as well. Just use the |
| `install' or `cp' command that you normally would (*note Install |
| mode::): |
| |
| a23# libtool --mode=install cp libhello.la /usr/local/lib/libhello.la |
| cp libhello.la /usr/local/lib/libhello.la |
| cp .libs/libhello.a /usr/local/lib/libhello.a |
| ranlib /usr/local/lib/libhello.a |
| a23# |
| |
| Note that the libtool library `libhello.la' is also installed, to |
| help libtool with uninstallation (*note Uninstall mode::) and linking |
| (*note Linking executables::) and to help programs with dlopening |
| (*note Dlopened modules::). |
| |
| Here is the shared library example: |
| |
| burger# libtool --mode=install install -c libhello.la \ |
| /usr/local/lib/libhello.la |
| install -c .libs/libhello.so.0.0 /usr/local/lib/libhello.so.0.0 |
| install -c libhello.la /usr/local/lib/libhello.la |
| install -c .libs/libhello.a /usr/local/lib/libhello.a |
| ranlib /usr/local/lib/libhello.a |
| burger# |
| |
| It is safe to specify the `-s' (strip symbols) flag if you use a |
| BSD-compatible install program when installing libraries. Libtool will |
| either ignore the `-s' flag, or will run a program that will strip only |
| debugging and compiler symbols from the library. |
| |
| Once the libraries have been put in place, there may be some |
| additional configuration that you need to do before using them. First, |
| you must make sure that where the library is installed actually agrees |
| with the `-rpath' flag you used to build it. |
| |
| Then, running `libtool -n finish LIBDIR' can give you further hints |
| on what to do (*note Finish mode::): |
| |
| burger# libtool -n finish /usr/local/lib |
| PATH="$PATH:/sbin" ldconfig -m /usr/local/lib |
| ----------------------------------------------------------------- |
| Libraries have been installed in: |
| /usr/local/lib |
| |
| To link against installed libraries in a given directory, LIBDIR, |
| you must use the `-LLIBDIR' flag during linking. |
| |
| You will also need to do one of the following: |
| - add LIBDIR to the `LD_LIBRARY_PATH' environment variable |
| during execution |
| - add LIBDIR to the `LD_RUN_PATH' environment variable |
| during linking |
| - use the `-RLIBDIR' linker flag |
| |
| See any operating system documentation about shared libraries for |
| more information, such as the ld and ld.so manual pages. |
| ----------------------------------------------------------------- |
| burger# |
| |
| After you have completed these steps, you can go on to begin using |
| the installed libraries. You may also install any executables that |
| depend on libraries you created. |
| |
| ---------- Footnotes ---------- |
| |
| (1) Don't strip static libraries though, or they will be unusable. |
| |
| |
| File: libtool.info, Node: Installing executables, Next: Static libraries, Prev: Installing libraries, Up: Using libtool |
| |
| 3.6 Installing executables |
| ========================== |
| |
| If you used libtool to link any executables against uninstalled libtool |
| libraries (*note Linking executables::), you need to use libtool to |
| install the executables after the libraries have been installed (*note |
| Installing libraries::). |
| |
| So, for our Ultrix example, we would run: |
| |
| a23# libtool --mode=install -c hell /usr/local/bin/hell |
| install -c hell /usr/local/bin/hell |
| a23# |
| |
| On shared library systems that require wrapper scripts, libtool just |
| ignores the wrapper script and installs the correct binary: |
| |
| burger# libtool --mode=install -c hell /usr/local/bin/hell |
| install -c .libs/hell /usr/local/bin/hell |
| burger# |
| |
| |
| File: libtool.info, Node: Static libraries, Prev: Installing executables, Up: Using libtool |
| |
| 3.7 Linking static libraries |
| ============================ |
| |
| Why return to `ar' and `ranlib' silliness when you've had a taste of |
| libtool? Well, sometimes it is desirable to create a static archive |
| that can never be shared. The most frequent case is when you have a |
| set of object files that you use to build several different libraries. |
| You can create a "convenience library" out of those objects, and link |
| against that with the other libraries, instead of listing all the |
| object files every time. |
| |
| If you just want to link this convenience library into programs, then |
| you could just ignore libtool entirely, and use the old `ar' and |
| `ranlib' commands (or the corresponding GNU Automake `_LIBRARIES' |
| rules). You can even install a convenience library using GNU Libtool, |
| though you probably don't want to and hence GNU Automake doesn't allow |
| you to do so. |
| |
| burger$ libtool --mode=install ./install-sh -c libhello.a \ |
| /local/lib/libhello.a |
| ./install-sh -c libhello.a /local/lib/libhello.a |
| ranlib /local/lib/libhello.a |
| burger$ |
| |
| Using libtool for static library installation protects your library |
| from being accidentally stripped (if the installer used the `-s' flag), |
| as well as automatically running the correct `ranlib' command. |
| |
| But libtool libraries are more than just collections of object files: |
| they can also carry library dependency information, which old archives |
| do not. If you want to create a libtool static convenience library, you |
| can omit the `-rpath' flag and use `-static' to indicate that you're |
| only interested in a static library. When you link a program with such |
| a library, libtool will actually link all object files and dependency |
| libraries into the program. |
| |
| If you omit both `-rpath' and `-static', libtool will create a |
| convenience library that can be used to create other libtool libraries, |
| even shared ones. Just like in the static case, the library behaves as |
| an alias to a set of object files and dependency libraries, but in this |
| case the object files are suitable for inclusion in shared libraries. |
| But be careful not to link a single convenience library, directly or |
| indirectly, into a single program or library, otherwise you may get |
| errors about symbol redefinitions. |
| |
| The key is remembering that a convenience library contains PIC |
| objects, and can be linked where a list of PIC objects makes sense; |
| i.e. into a shared library. A static convenience library contains |
| non-PIC objects, so can be linked into an old static library, or a |
| program. |
| |
| When GNU Automake is used, you should use `noinst_LTLIBRARIES' |
| instead of `lib_LTLIBRARIES' for convenience libraries, so that the |
| `-rpath' option is not passed when they are linked. |
| |
| As a rule of thumb, link a libtool convenience library into at most |
| one libtool library, and never into a program, and link libtool static |
| convenience libraries only into programs, and only if you need to carry |
| library dependency information to the user of the static convenience |
| library. |
| |
| Another common situation where static linking is desirable is in |
| creating a standalone binary. Use libtool to do the linking and add the |
| `-all-static' flag. |
| |
| |
| File: libtool.info, Node: Invoking libtool, Next: Integrating libtool, Prev: Using libtool, Up: Top |
| |
| 4 Invoking `libtool' |
| ******************** |
| |
| The `libtool' program has the following synopsis: |
| |
| libtool [OPTION]... [MODE-ARG]... |
| |
| and accepts the following options: |
| |
| `--config' |
| Display libtool configuration variables and exit. |
| |
| `--debug' |
| Dump a trace of shell script execution to standard output. This |
| produces a lot of output, so you may wish to pipe it to `less' (or |
| `more') or redirect to a file. |
| |
| `-n' |
| `--dry-run' |
| Don't create, modify, or delete any files, just show what commands |
| would be executed by libtool. |
| |
| `--features' |
| Display basic configuration options. This provides a way for |
| packages to determine whether shared or static libraries will be |
| built. |
| |
| `--finish' |
| Same as `--mode=finish'. |
| |
| `-h' |
| Display short help message. |
| |
| `--help' |
| Display a help message and exit. If `--mode=MODE' is specified, |
| then detailed help for MODE is displayed. |
| |
| `--help-all' |
| Display help for the general options as well as detailed help for |
| each operation mode, and exit. |
| |
| `--mode=MODE' |
| Use MODE as the operation mode. When using libtool from the |
| command line, you can give just MODE (or a unique abbreviation of |
| it) as the first argument as a shorthand for the full |
| `--mode=MODE'. For example, the following are equivalent: |
| |
| $ libtool --mode=execute --dry-run gdb prog.exe |
| $ libtool execute --dry-run gdb prog.exe |
| $ libtool exe --dry-run gdb prog.exe |
| $ libtool e --dry-run gdb prog.exe |
| |
| MODE must be set to one of the following: |
| |
| `compile' |
| Compile a source file into a libtool object. |
| |
| `execute' |
| Automatically set the library path so that another program |
| can use uninstalled libtool-generated programs or libraries. |
| |
| `link' |
| Create a library or an executable. |
| |
| `install' |
| Install libraries or executables. |
| |
| `finish' |
| Complete the installation of libtool libraries on the system. |
| |
| `uninstall' |
| Delete installed libraries or executables. |
| |
| `clean' |
| Delete uninstalled libraries or executables. |
| |
| `--tag=TAG' |
| Use configuration variables from tag TAG (*note Tags::). |
| |
| `--preserve-dup-deps' |
| Do not remove duplicate dependencies in libraries. When building |
| packages with static libraries, the libraries may depend |
| circularly on each other (shared libs can too, but for those it |
| doesn't matter), so there are situations, where -la -lb -la is |
| required, and the second -la may not be stripped or the link will |
| fail. In cases where these duplications are required, this option |
| will preserve them, only stripping the libraries that libtool |
| knows it can safely. |
| |
| `--quiet' |
| `--silent' |
| Do not print out any progress or informational messages. |
| |
| `-v' |
| `--verbose' |
| Print out progress and informational messages (enabled by default), |
| as well as additional messages not ordinary seen by default. |
| |
| `--no-quiet' |
| `--no-silent' |
| Print out the progress and informational messages that are seen by |
| default. This option has no effect on whether the additional |
| messages seen in `--verbose' mode are shown. |
| |
| `--no-verbose' |
| Do not print out any additional informational messages beyond |
| those ordinarily seen by default. This option has no effect on |
| whether the ordinary progress and informational messages enabled |
| by `--no-quiet' are shown. |
| |
| Thus, there are now three different message levels (not counting |
| `--debug'), depending on whether the normal messages and/or the |
| additional verbose messages are displayed. Note that there is no |
| mechanism to diplay verbose messages, without also displaying |
| normal messages. |
| |
| *default* |
| Normal messages are displayed, verbose messages are not |
| displayed. In addition to being the default mode, it can be |
| forcibly achieved by using both option `--no-verbose' and |
| either option `--no-silent' or option `--no-quiet'. |
| |
| *silent* |
| Neither normal messages nor verbose messages are displayed. |
| This mode can be achieved using either option `--silent' or |
| option `--quiet'. |
| |
| *verbose* |
| Both normal messages and verbose messages are displayed. This |
| mode can be achieved using either option `-v' or option |
| `--verbose'. |
| |
| `--version' |
| Print libtool version information and exit. |
| |
| The current `libtool' implementation is done with a shell script |
| that needs to be invoked by the shell which `configure' chose for |
| configuring `libtool' (*note The Autoconf Manual: |
| (autoconf)config.status Invocation.). This shell is set in the |
| she-bang (`#!') line of the `libtool' script. Using a different shell |
| may cause undefined behavior. |
| |
| The MODE-ARGS are a variable number of arguments, depending on the |
| selected operation mode. In general, each MODE-ARG is interpreted by |
| programs libtool invokes, rather than libtool itself. |
| |
| * Menu: |
| |
| * Compile mode:: Creating library object files. |
| * Link mode:: Generating executables and libraries. |
| * Execute mode:: Debugging libtool-generated programs. |
| * Install mode:: Making libraries and executables public. |
| * Finish mode:: Completing a library installation. |
| * Uninstall mode:: Removing installed executables and libraries. |
| * Clean mode:: Removing uninstalled executables and libraries. |
| |
| |
| File: libtool.info, Node: Compile mode, Next: Link mode, Up: Invoking libtool |
| |
| 4.1 Compile mode |
| ================ |
| |
| For "compile" mode, MODE-ARGS is a compiler command to be used in |
| creating a "standard" object file. These arguments should begin with |
| the name of the C compiler, and contain the `-c' compiler flag so that |
| only an object file is created. |
| |
| Libtool determines the name of the output file by removing the |
| directory component from the source file name, then substituting the |
| source code suffix (e.g. `.c' for C source code) with the library |
| object suffix, `.lo'. |
| |
| If shared libraries are being built, any necessary PIC generation |
| flags are substituted into the compilation command. |
| |
| The following components of MODE-ARGS are treated specially: |
| |
| `-o' |
| Note that the `-o' option is now fully supported. It is emulated |
| on the platforms that don't support it (by locking and moving the |
| objects), so it is really easy to use libtool, just with minor |
| modifications to your Makefiles. Typing for example |
| libtool --mode=compile gcc -c foo/x.c -o foo/x.lo |
| will do what you expect. |
| |
| Note, however, that, if the compiler does not support `-c' and |
| `-o', it is impossible to compile `foo/x.c' without overwriting an |
| existing `./x.o'. Therefore, if you do have a source file |
| `./x.c', make sure you introduce dependencies in your `Makefile' |
| to make sure `./x.o' (or `./x.lo') is re-created after any |
| sub-directory's `x.lo': |
| |
| x.o x.lo: foo/x.lo bar/x.lo |
| |
| This will also ensure that make won't try to use a temporarily |
| corrupted `x.o' to create a program or library. It may cause |
| needless recompilation on platforms that support `-c' and `-o' |
| together, but it's the only way to make it safe for those that |
| don't. |
| |
| `-no-suppress' |
| If both PIC and non-PIC objects are being built, libtool will |
| normally suppress the compiler output for the PIC object |
| compilation to save showing very similar, if not identical |
| duplicate output for each object. If the `-no-suppress' option is |
| given in compile mode, libtool will show the compiler output for |
| both objects. |
| |
| `-prefer-pic' |
| Libtool will try to build only PIC objects. |
| |
| `-prefer-non-pic' |
| Libtool will try to build only non-PIC objects. |
| |
| `-shared' |
| Even if Libtool was configured with `--enable-static', the object |
| file Libtool builds will not be suitable for static linking. |
| Libtool will signal an error if it was configured with |
| `--disable-shared', or if the host does not support shared |
| libraries. |
| |
| `-static' |
| Even if libtool was configured with `--disable-static', the object |
| file Libtool builds *will* be suitable for static linking. |
| |
| `-Wc,FLAG' |
| `-Xcompiler FLAG' |
| Pass a flag directly to the compiler. With `-Wc,', multiple flags |
| may be separated by commas, whereas `-Xcompiler ' passes through |
| commas unchanged. |
| |
| |
| File: libtool.info, Node: Link mode, Next: Execute mode, Prev: Compile mode, Up: Invoking libtool |
| |
| 4.2 Link mode |
| ============= |
| |
| "Link" mode links together object files (including library objects) to |
| form another library or to create an executable program. |
| |
| MODE-ARGS consist of a command using the C compiler to create an |
| output file (with the `-o' flag) from several object files. |
| |
| The following components of MODE-ARGS are treated specially: |
| |
| `-all-static' |
| If OUTPUT-FILE is a program, then do not link it against any |
| shared libraries at all. If OUTPUT-FILE is a library, then only |
| create a static library. In general, this flag cannot be used |
| together with `disable-static' (*note LT_INIT::). |
| |
| `-avoid-version' |
| Tries to avoid versioning (*note Versioning::) for libraries and |
| modules, i.e. no version information is stored and no symbolic |
| links are created. If the platform requires versioning, this |
| option has no effect. |
| |
| `-bindir' |
| Pass the absolute name of the directory for installing executable |
| programs (*note Directory Variables: (standards)Directory |
| Variables.). `libtool' may use this value to install shared |
| libraries there on systems that do not provide for any library |
| hardcoding and use the directory of a program and the `PATH' |
| variable as library search path. This is typically used for DLLs |
| on Windows or other systems using the PE (Portable Executable) |
| format. On other systems, `-bindir' is ignored. The default |
| value used is `LIBDIR/../bin' for libraries installed to `LIBDIR'. |
| You should not use `-bindir' for modules. |
| |
| `-dlopen FILE' |
| Same as `-dlpreopen FILE', if native dlopening is not supported on |
| the host platform (*note Dlopened modules::) or if the program is |
| linked with `-static', `-static-libtool-libs', or `-all-static'. |
| Otherwise, no effect. If FILE is `self' Libtool will make sure |
| that the program can `dlopen' itself, either by enabling |
| `-export-dynamic' or by falling back to `-dlpreopen self'. |
| |
| `-dlpreopen FILE' |
| Link FILE into the output program, and add its symbols to the list |
| of preloaded symbols (*note Dlpreopening::). If FILE is `self', |
| the symbols of the program itself will be added to preloaded |
| symbol lists. If FILE is `force' Libtool will make sure that a |
| preloaded symbol list is always _defined_, regardless of whether |
| it's empty or not. |
| |
| `-export-dynamic' |
| Allow symbols from OUTPUT-FILE to be resolved with `dlsym' (*note |
| Dlopened modules::). |
| |
| `-export-symbols SYMFILE' |
| Tells the linker to export only the symbols listed in SYMFILE. |
| The symbol file should end in `.sym' and must contain the name of |
| one symbol per line. This option has no effect on some platforms. |
| By default all symbols are exported. |
| |
| `-export-symbols-regex REGEX' |
| Same as `-export-symbols', except that only symbols matching the |
| regular expression REGEX are exported. By default all symbols are |
| exported. |
| |
| `-LLIBDIR' |
| Search LIBDIR for required libraries that have already been |
| installed. |
| |
| `-lNAME' |
| OUTPUT-FILE requires the installed library `libNAME'. This option |
| is required even when OUTPUT-FILE is not an executable. |
| |
| `-module' |
| Creates a library that can be dlopened (*note Dlopened modules::). |
| This option doesn't work for programs. Module names don't need to |
| be prefixed with `lib'. In order to prevent name clashes, |
| however, `libNAME' and `NAME' must not be used at the same time in |
| your package. |
| |
| `-no-fast-install' |
| Disable fast-install mode for the executable OUTPUT-FILE. Useful |
| if the program won't be necessarily installed. |
| |
| `-no-install' |
| Link an executable OUTPUT-FILE that can't be installed and |
| therefore doesn't need a wrapper script on systems that allow |
| hardcoding of library paths. Useful if the program is only used |
| in the build tree, e.g., for testing or generating other files. |
| |
| `-no-undefined' |
| Declare that OUTPUT-FILE does not depend on any libraries other |
| than the ones listed on the command line, i.e., after linking, it |
| will not have unresolved symbols. Some platforms require all |
| symbols in shared libraries to be resolved at library creation |
| (*note Inter-library dependencies::), and using this parameter |
| allows `libtool' to assume that this will not happen. |
| |
| `-o OUTPUT-FILE' |
| Create OUTPUT-FILE from the specified objects and libraries. |
| |
| `-objectlist FILE' |
| Use a list of object files found in FILE to specify objects. |
| |
| `-precious-files-regex REGEX' |
| Prevents removal of files from the temporary output directory whose |
| names match this regular expression. You might specify `\.bbg?$' |
| to keep those files created with `gcc -ftest-coverage' for example. |
| |
| `-release RELEASE' |
| Specify that the library was generated by release RELEASE of your |
| package, so that users can easily tell which versions are newer |
| than others. Be warned that no two releases of your package will |
| be binary compatible if you use this flag. If you want binary |
| compatibility, use the `-version-info' flag instead (*note |
| Versioning::). |
| |
| `-rpath LIBDIR' |
| If OUTPUT-FILE is a library, it will eventually be installed in |
| LIBDIR. If OUTPUT-FILE is a program, add LIBDIR to the run-time |
| path of the program. On platforms that don't support hardcoding |
| library paths into executables and only search PATH for shared |
| libraries, such as when OUTPUT-FILE is a Windows (or other PE |
| platform) DLL, the `.la' control file will be installed in LIBDIR, |
| but see `-bindir' above for the eventual destination of the `.dll' |
| or other library file itself. |
| |
| `-R LIBDIR' |
| If OUTPUT-FILE is a program, add LIBDIR to its run-time path. If |
| OUTPUT-FILE is a library, add `-RLIBDIR' to its DEPENDENCY_LIBS, |
| so that, whenever the library is linked into a program, LIBDIR |
| will be added to its run-time path. |
| |
| `-shared' |
| If OUTPUT-FILE is a program, then link it against any uninstalled |
| shared libtool libraries (this is the default behavior). If |
| OUTPUT-FILE is a library, then only create a shared library. In |
| the later case, libtool will signal an error if it was configured |
| with `--disable-shared', or if the host does not support shared |
| libraries. |
| |
| `-shrext SUFFIX' |
| If OUTPUT-FILE is a libtool library, replace the system's standard |
| file name extension for shared libraries with SUFFIX (most systems |
| use `.so' here). This option is helpful in certain cases where an |
| application requires that shared libraries (typically modules) |
| have an extension other than the default one. Please note you |
| must supply the full file name extension including any leading dot. |
| |
| `-static' |
| If OUTPUT-FILE is a program, then do not link it against any |
| uninstalled shared libtool libraries. If OUTPUT-FILE is a |
| library, then only create a static library. |
| |
| `-static-libtool-libs' |
| If OUTPUT-FILE is a program, then do not link it against any |
| shared libtool libraries. If OUTPUT-FILE is a library, then only |
| create a static library. |
| |
| `-version-info CURRENT[:REVISION[:AGE]]' |
| If OUTPUT-FILE is a libtool library, use interface version |
| information CURRENT, REVISION, and AGE to build it (*note |
| Versioning::). Do *not* use this flag to specify package release |
| information, rather see the `-release' flag. |
| |
| `-version-number MAJOR[:MINOR[:REVISION]]' |
| If OUTPUT-FILE is a libtool library, compute interface version |
| information so that the resulting library uses the specified |
| major, minor and revision numbers. This is designed to permit |
| libtool to be used with existing projects where identical version |
| numbers are already used across operating systems. New projects |
| should use the `-version-info' flag instead. |
| |
| `-weak LIBNAME' |
| if OUTPUT-FILE is a libtool library, declare that it provides a |
| weak LIBNAME interface. This is a hint to libtool that there is |
| no need to append LIBNAME to the list of dependency libraries of |
| OUTPUT-FILE, because linking against OUTPUT-FILE already supplies |
| the same interface (*note Linking with dlopened modules::). |
| |
| `-Wc,FLAG' |
| `-Xcompiler FLAG' |
| Pass a linker-specific flag directly to the compiler. With `-Wc,', |
| multiple flags may be separated by commas, whereas `-Xcompiler ' |
| passes through commas unchanged. |
| |
| `-Wl,FLAG' |
| `-Xlinker FLAG' |
| Pass a linker-specific flag directly to the linker. |
| |
| `-XCClinker FLAG' |
| Pass a link-specific flag to the compiler driver (`CC') during |
| linking. |
| |
| If the OUTPUT-FILE ends in `.la', then a libtool library is created, |
| which must be built only from library objects (`.lo' files). The |
| `-rpath' option is required. In the current implementation, libtool |
| libraries may not depend on other uninstalled libtool libraries (*note |
| Inter-library dependencies::). |
| |
| If the OUTPUT-FILE ends in `.a', then a standard library is created |
| using `ar' and possibly `ranlib'. |
| |
| If OUTPUT-FILE ends in `.o' or `.lo', then a reloadable object file |
| is created from the input files (generally using `ld -r'). This method |
| is often called "partial linking". |
| |
| Otherwise, an executable program is created. |
| |
| |
| File: libtool.info, Node: Execute mode, Next: Install mode, Prev: Link mode, Up: Invoking libtool |
| |
| 4.3 Execute mode |
| ================ |
| |
| For "execute" mode, the library path is automatically set, then a |
| program is executed. |
| |
| The first of the MODE-ARGS is treated as a program name, with the |
| rest as arguments to that program. |
| |
| The following components of MODE-ARGS are treated specially: |
| |
| `-dlopen FILE' |
| Add the directory containing FILE to the library path. |
| |
| This mode sets the library path environment variable according to any |
| `-dlopen' flags. |
| |
| If any of the ARGS are libtool executable wrappers, then they are |
| translated into the name of their corresponding uninstalled binary, and |
| any of their required library directories are added to the library path. |
| |
| |
| File: libtool.info, Node: Install mode, Next: Finish mode, Prev: Execute mode, Up: Invoking libtool |
| |
| 4.4 Install mode |
| ================ |
| |
| In "install" mode, libtool interprets most of the elements of MODE-ARGS |
| as an installation command beginning with `cp', or a BSD-compatible |
| `install' program. |
| |
| The following components of MODE-ARGS are treated specially: |
| |
| `-inst-prefix-dir INST-PREFIX-DIR' |
| When installing into a temporary staging area, rather than the |
| final `prefix', this argument is used to reflect the temporary |
| path, in much the same way `automake' uses `DESTDIR'. For |
| instance, if `prefix' is `/usr/local', but INST-PREFIX-DIR is |
| `/tmp', then the object will be installed under `/tmp/usr/local/'. |
| If the installed object is a libtool library, then the internal |
| fields of that library will reflect only `prefix', not |
| INST-PREFIX-DIR: |
| |
| # Directory that this library needs to be installed in: |
| libdir='/usr/local/lib' |
| |
| not |
| |
| # Directory that this library needs to be installed in: |
| libdir='/tmp/usr/local/lib' |
| |
| `inst-prefix' is also used to insure that if the installed object |
| must be relinked upon installation, that it is relinked against |
| the libraries in INST-PREFIX-DIR/`prefix', not `prefix'. |
| |
| In truth, this option is not really intended for use when calling |
| libtool directly; it is automatically used when `libtool |
| --mode=install' calls `libtool --mode=relink'. Libtool does this |
| by analyzing the destination path given in the original `libtool |
| --mode=install' command and comparing it to the expected |
| installation path established during `libtool --mode=link'. |
| |
| Thus, end-users need change nothing, and `automake'-style `make |
| install DESTDIR=/tmp' will Just Work(tm) most of the time. For |
| systems where fast installation can not be turned on, relinking |
| may be needed. In this case, a `DESTDIR' install will fail. |
| |
| Currently it is not generally possible to install into a temporary |
| staging area that contains needed third-party libraries which are |
| not yet visible at their final location. |
| |
| The rest of the MODE-ARGS are interpreted as arguments to the `cp' |
| or `install' command. |
| |
| The command is run, and any necessary unprivileged post-installation |
| commands are also completed. |
| |
| |
| File: libtool.info, Node: Finish mode, Next: Uninstall mode, Prev: Install mode, Up: Invoking libtool |
| |
| 4.5 Finish mode |
| =============== |
| |
| "Finish" mode has two functions. One is to help system administrators |
| install libtool libraries so that they can be located and linked into |
| user programs. To invoke this functionality, pass the name of a library |
| directory as MODE-ARG. Running this command may require superuser |
| privileges, and the `--dry-run' option may be useful. |
| |
| The second is to facilitate transferring libtool libraries to a |
| native compilation environment after they were built in a |
| cross-compilation environment. Cross-compilation environments may rely |
| on recent libtool features, and running libtool in finish mode will |
| make it easier to work with older versions of libtool. This task is |
| performed whenever the MODE-ARG is a `.la' file. |
| |
| |
| File: libtool.info, Node: Uninstall mode, Next: Clean mode, Prev: Finish mode, Up: Invoking libtool |
| |
| 4.6 Uninstall mode |
| ================== |
| |
| "Uninstall" mode deletes installed libraries, executables and objects. |
| |
| The first MODE-ARG is the name of the program to use to delete files |
| (typically `/bin/rm'). |
| |
| The remaining MODE-ARGS are either flags for the deletion program |
| (beginning with a `-'), or the names of files to delete. |
| |
| |
| File: libtool.info, Node: Clean mode, Prev: Uninstall mode, Up: Invoking libtool |
| |
| 4.7 Clean mode |
| ============== |
| |
| "Clean" mode deletes uninstalled libraries, executables, objects and |
| libtool's temporary files associated with them. |
| |
| The first MODE-ARG is the name of the program to use to delete files |
| (typically `/bin/rm'). |
| |
| The remaining MODE-ARGS are either flags for the deletion program |
| (beginning with a `-'), or the names of files to delete. |
| |
| |
| File: libtool.info, Node: Integrating libtool, Next: Other languages, Prev: Invoking libtool, Up: Top |
| |
| 5 Integrating libtool with your package |
| *************************************** |
| |
| This chapter describes how to integrate libtool with your packages so |
| that your users can install hassle-free shared libraries. |
| |
| There are several ways in which Libtool may be integrated in your |
| package, described in the following sections. Typically, the Libtool |
| macro files as well as `ltmain.sh' are copied into your package using |
| `libtoolize' and `aclocal' after setting up the `configure.ac' and |
| toplevel `Makefile.am', then `autoconf' adds the needed tests to the |
| `configure' script. These individual steps are often automated with |
| `autoreconf'. |
| |
| Here is a diagram showing how such a typical Libtool configuration |
| works when preparing a package for distribution, assuming that `m4' has |
| been chosen as location for additional Autoconf macros, and `build-aux' |
| as location for auxiliary build tools (*note The Autoconf Manual: |
| (autoconf)Input.): |
| |
| libtool.m4 -----. .--> aclocal.m4 -----. |
| ltoptions.m4 ---+ .-> aclocal* -+ +--> autoconf* |
| ltversion.m4 ---+--+ `--> [copy in m4/] --+ | |
| ltsugar.m4 -----+ | ^ | \/ |
| lt~obsolete.m4 -+ +-> libtoolize* -----' | configure |
| [ltdl.m4] ------+ | | |
| `----------------------------------' |
| |
| ltmain.sh -----------> libtoolize* -> [copy in build-aux/] |
| |
| During configuration, the `libtool' script is generated either |
| through `config.status' or `config.lt': |
| |
| .--> config.status* --. |
| configure* --+ +--> libtool |
| `--> [config.lt*] ----' ^ |
| | |
| ltmain.sh --------------------------------' |
| |
| At `make' run time, `libtool' is then invoked as needed as a wrapper |
| around compilers, linkers, install and cleanup programs. |
| |
| There are alternatives choices to several parts of the setup; for |
| example, the Libtool macro files can either be copied or symlinked into |
| the package, or copied into `aclocal.m4'. As another example, an |
| external, pre-configured `libtool' script may be used, by-passing most |
| of the tests and package-specific setup for Libtool. |
| |
| * Menu: |
| |
| * Autoconf macros:: Autoconf macros exported by libtool. |
| * Makefile rules:: Writing `Makefile' rules for libtool. |
| * Using Automake:: Automatically supporting libtool. |
| * Configuring:: Configuring libtool for a host system. |
| * Distributing:: What files to distribute with your package. |
| * Static-only libraries:: Sometimes shared libraries are just a pain. |
| |
| |
| File: libtool.info, Node: Autoconf macros, Next: Makefile rules, Up: Integrating libtool |
| |
| 5.1 Autoconf macros exported by libtool |
| ======================================= |
| |
| Libtool uses a number of macros to interrogate the host system when it |
| is being built, and you can use some of them yourself too. Although |
| there are a great many other macros in the libtool installed m4 files, |
| these do not form part of the published interface, and are subject to |
| change between releases. |
| |
| Macros in the `LT_CMD_' namespace check for various shell commands: |
| |
| -- Macro: LT_CMD_MAX_LEN |
| Finds the longest command line that can be safely passed to |
| `$SHELL' without being truncated, and store in the shell variable |
| `$max_cmd_len'. It is only an approximate value, but command |
| lines of this length or shorter are guaranteed not to be truncated. |
| |
| Macros in the `LT_FUNC_' namespace check characteristics of library |
| functions: |
| |
| -- Macro: LT_FUNC_DLSYM_USCORE |
| `AC_DEFINE' the preprocessor symbol `DLSYM_USCORE' if we have to |
| add an underscore to symbol-names passed in to `dlsym'. |
| |
| Macros in the `LT_LIB_' namespace check characteristics of system |
| libraries: |
| |
| -- Macro: LT_LIB_M |
| Set `LIBM' to the math library or libraries required on this |
| machine, if any. |
| |
| -- Macro: LT_LIB_DLLOAD |
| This is the macro used by `libltdl' to determine which dlloaders |
| to use on this machine, if any. Several shell variables are set |
| (and `AC_SUBST'ed) depending on the dlload interfaces are |
| available on this machine. `LT_DLLOADERS' contains a list of |
| libtool libraries that can be used, and if necessary also sets |
| `LIBADD_DLOPEN' if additional system libraries are required by the |
| `dlopen' loader, and `LIBADD_SHL_LOAD' if additional system |
| libraries are required by the `shl_load' loader, respectively. |
| Finally some symbols are set in `config.h' depending on the |
| loaders that are found to work: `HAVE_LIBDL', `HAVE_SHL_LOAD', |
| `HAVE_DYLD', `HAVE_DLD'. |
| |
| Macros in the `LT_PATH_' namespace search the system for the full path |
| to particular system commands: |
| |
| -- Macro: LT_PATH_LD |
| Add a `--with-gnu-ld' option to `configure'. Try to find the path |
| to the linker used by `$CC', and whether it is the GNU linker. |
| The result is stored in the shell variable `$LD', which is |
| `AC_SUBST'ed. |
| |
| -- Macro: LT_PATH_NM |
| Try to find a BSD-compatible `nm' or a MS-compatible `dumpbin' |
| command on this machine. The result is stored in the shell |
| variable `$NM', which is `AC_SUBST'ed. |
| |
| Macros in the `LT_SYS_' namespace probe for system characteristics: |
| |
| -- Macro: LT_SYS_DLOPEN_SELF |
| Tests whether a program can dlopen itself, and then also whether |
| the same program can still dlopen itself when statically linked. |
| Results are stored in the shell variables `$enable_dlopen_self' and |
| `enable_dlopen_self_static' respectively. |
| |
| -- Macro: LT_SYS_DLOPEN_DEPLIBS |
| Define the preprocessor symbol `LTDL_DLOPEN_DEPLIBS' if the OS |
| needs help to load dependent libraries for `dlopen' (or |
| equivalent). |
| |
| -- Macro: LT_SYS_DLSEARCH_PATH |
| Define the preprocessor symbol `LT_DLSEARCH_PATH' to the system |
| default library search path. |
| |
| -- Macro: LT_SYS_MODULE_EXT |
| Define the preprocessor symbol `LT_MODULE_EXT' to the extension |
| used for runtime loadable modules. If you use libltdl to open |
| modules, then you can simply use the libtool library extension, |
| `.la'. |
| |
| -- Macro: LT_SYS_MODULE_PATH |
| Define the preprocessor symbol `LT_MODULE_PATH_VAR' to the name of |
| the shell environment variable that determines the run-time module |
| search path. |
| |
| -- Macro: LT_SYS_SYMBOL_USCORE |
| Set the shell variable `sys_symbol_underscore' to `no' unless the |
| compiler prefixes global symbols with an underscore. |
| |
| |
| File: libtool.info, Node: Makefile rules, Next: Using Automake, Prev: Autoconf macros, Up: Integrating libtool |
| |
| 5.2 Writing `Makefile' rules for libtool |
| ======================================== |
| |
| Libtool is fully integrated with Automake (*note Introduction: |
| (automake)Top.), starting with Automake version 1.2. |
| |
| If you want to use libtool in a regular `Makefile' (or |
| `Makefile.in'), you are on your own. If you're not using Automake, and |
| you don't know how to incorporate libtool into your package you need to |
| do one of the following: |
| |
| 1. Download the latest Automake distribution from your nearest GNU |
| mirror, install it, and start using it. |
| |
| 2. Learn how to write `Makefile' rules by hand. They're sometimes |
| complex, but if you're clever enough to write rules for compiling |
| your old libraries, then you should be able to figure out new |
| rules for libtool libraries (hint: examine the `Makefile.in' in |
| the `tests/demo' subdirectory of the libtool distribution... note |
| especially that it was automatically generated from the |
| `Makefile.am' by Automake). |
| |
| |
| File: libtool.info, Node: Using Automake, Next: Configuring, Prev: Makefile rules, Up: Integrating libtool |
| |
| 5.3 Using Automake with libtool |
| =============================== |
| |
| Libtool library support is implemented under the `LTLIBRARIES' primary. |
| |
| Here are some samples from the Automake `Makefile.am' in the libtool |
| distribution's `demo' subdirectory. |
| |
| First, to link a program against a libtool library, just use the |
| `program_LDADD'(1) variable: |
| |
| bin_PROGRAMS = hell hell_static |
| |
| # Build hell from main.c and libhello.la |
| hell_SOURCES = main.c |
| hell_LDADD = libhello.la |
| |
| # Create a statically linked version of hell. |
| hell_static_SOURCES = main.c |
| hell_static_LDADD = libhello.la |
| hell_static_LDFLAGS = -static |
| |
| You may use the `program_LDFLAGS' variable to stuff in any flags you |
| want to pass to libtool while linking `program' (such as `-static' to |
| avoid linking uninstalled shared libtool libraries). |
| |
| Building a libtool library is almost as trivial... note the use of |
| `libhello_la_LDFLAGS' to pass the `-version-info' (*note Versioning::) |
| option to libtool: |
| |
| # Build a libtool library, libhello.la for installation in libdir. |
| lib_LTLIBRARIES = libhello.la |
| libhello_la_SOURCES = hello.c foo.c |
| libhello_la_LDFLAGS = -version-info 3:12:1 |
| |
| The `-rpath' option is passed automatically by Automake (except for |
| libraries listed as `noinst_LTLIBRARIES'), so you should not specify it. |
| |
| *Note Building a Shared Library: (automake)A Shared Library, for |
| more information. |
| |
| ---------- Footnotes ---------- |
| |
| (1) Since GNU Automake 1.5, the flags `-dlopen' or `-dlpreopen' |
| (*note Link mode::) can be employed with the `program_LDADD' variable. |
| Unfortunately, older releases didn't accept these flags, so if you are |
| stuck with an ancient Automake, we recommend quoting the flag itself, |
| and setting `program_DEPENDENCIES' too: |
| |
| program_LDADD = "-dlopen" libfoo.la |
| program_DEPENDENCIES = libfoo.la |
| |
| |
| File: libtool.info, Node: Configuring, Next: Distributing, Prev: Using Automake, Up: Integrating libtool |
| |
| 5.4 Configuring libtool |
| ======================= |
| |
| Libtool requires intimate knowledge of your compiler suite and operating |
| system in order to be able to create shared libraries and link against |
| them properly. When you install the libtool distribution, a |
| system-specific libtool script is installed into your binary directory. |
| |
| However, when you distribute libtool with your own packages (*note |
| Distributing::), you do not always know the compiler suite and |
| operating system that are used to compile your package. |
| |
| For this reason, libtool must be "configured" before it can be used. |
| This idea should be familiar to anybody who has used a GNU `configure' |
| script. `configure' runs a number of tests for system features, then |
| generates the `Makefile's (and possibly a `config.h' header file), |
| after which you can run `make' and build the package. |
| |
| Libtool adds its own tests to your `configure' script in order to |
| generate a libtool script for the installer's host machine. |
| |
| * Menu: |
| |
| * LT_INIT:: Configuring `libtool' in `configure.ac'. |
| * Configure notes:: Platform-specific notes for configuration. |
| |
| |
| File: libtool.info, Node: LT_INIT, Next: Configure notes, Up: Configuring |
| |
| 5.4.1 The `LT_INIT' macro |
| ------------------------- |
| |
| If you are using GNU Autoconf (or Automake), you should add a call to |
| `LT_INIT' to your `configure.ac' file. This macro adds many new tests |
| to the `configure' script so that the generated libtool script will |
| understand the characteristics of the host. It's the most important of |
| a number of macros defined by Libtool: |
| |
| -- Macro: LT_PREREQ (VERSION) |
| Ensure that a recent enough version of Libtool is being used. If |
| the version of Libtool used for `LT_INIT' is earlier than VERSION, |
| print an error message to the standard error output and exit with |
| failure (exit status is 63). For example: |
| |
| LT_PREREQ([2.4.2]) |
| |
| -- Macro: LT_INIT (OPTIONS) |
| -- Macro: AC_PROG_LIBTOOL |
| -- Macro: AM_PROG_LIBTOOL |
| Add support for the `--enable-shared', `--disable-shared', |
| `--enable-static', `--disable-static', `--with-pic', and |
| `--without-pic' `configure' flags.(1) `AC_PROG_LIBTOOL' and |
| `AM_PROG_LIBTOOL' are deprecated names for older versions of this |
| macro; `autoupdate' will upgrade your `configure.ac' files. |
| |
| By default, this macro turns on shared libraries if they are |
| available, and also enables static libraries if they don't |
| conflict with the shared libraries. You can modify these defaults |
| by passing either `disable-shared' or `disable-static' in the |
| option list to `LT_INIT', or using `AC_DISABLE_SHARED' or |
| `AC_DISABLE_STATIC'. |
| |
| # Turn off shared libraries during beta-testing, since they |
| # make the build process take too long. |
| LT_INIT([disable-shared]) |
| |
| The user may specify modified forms of the configure flags |
| `--enable-shared' and `--enable-static' to choose whether shared |
| or static libraries are built based on the name of the package. |
| For example, to have shared `bfd' and `gdb' libraries built, but |
| not shared `libg++', you can run all three `configure' scripts as |
| follows: |
| |
| trick$ ./configure --enable-shared=bfd,gdb |
| |
| In general, specifying `--enable-shared=PKGS' is the same as |
| configuring with `--enable-shared' every package named in the |
| comma-separated PKGS list, and every other package with |
| `--disable-shared'. The `--enable-static=PKGS' flag behaves |
| similarly, but it uses `--enable-static' and `--disable-static'. |
| The same applies to the `--enable-fast-install=PKGS' flag, which |
| uses `--enable-fast-install' and `--disable-fast-install'. |
| |
| The package name `default' matches any packages that have not set |
| their name in the `PACKAGE' environment variable. |
| |
| The `--with-pic' and `--without-pic' configure flags can be used |
| to specify whether or not `libtool' uses PIC objects. By default, |
| `libtool' uses PIC objects for shared libraries and non-PIC |
| objects for static libraries. The `--with-pic' option also |
| accepts a comma-separated list of package names. Specifying |
| `--with-pic=PKGS' is the same as configuring every package in PKGS |
| with `--with-pic' and every other package with the default |
| configuration. The package name `default' is treated the same as |
| for `--enable-shared' and `--enable-static'. |
| |
| This macro also sets the shell variable `LIBTOOL_DEPS', that you |
| can use to automatically update the libtool script if it becomes |
| out-of-date. In order to do that, add to your `configure.ac': |
| |
| LT_INIT |
| AC_SUBST([LIBTOOL_DEPS]) |
| |
| and, to `Makefile.in' or `Makefile.am': |
| |
| LIBTOOL_DEPS = @LIBTOOL_DEPS@ |
| libtool: $(LIBTOOL_DEPS) |
| $(SHELL) ./config.status libtool |
| |
| If you are using GNU Automake, you can omit the assignment, as |
| Automake will take care of it. You'll obviously have to create |
| some dependency on `libtool'. |
| |
| Aside from `disable-static' and `disable-shared', there are other |
| options that you can pass to `LT_INIT' to modify its behaviour. |
| Here is a full list: |
| |
| `dlopen' |
| Enable checking for dlopen support. This option should be |
| used if the package makes use of the `-dlopen' and |
| `-dlpreopen' libtool flags, otherwise libtool will assume |
| that the system does not support dlopening. |
| |
| `win32-dll' |
| This option should be used if the package has been ported to |
| build clean dlls on win32 platforms. Usually this means that |
| any library data items are exported with |
| `__declspec(dllexport)' and imported with |
| `__declspec(dllimport)'. If this macro is not used, libtool |
| will assume that the package libraries are not dll clean and |
| will build only static libraries on win32 hosts. |
| |
| Provision must be made to pass `-no-undefined' to `libtool' |
| in link mode from the package `Makefile'. Naturally, if you |
| pass `-no-undefined', you must ensure that all the library |
| symbols *really are* defined at link time! |
| |
| `disable-fast-install' |
| Change the default behaviour for `LT_INIT' to disable |
| optimization for fast installation. The user may still |
| override this default, depending on platform support, by |
| specifying `--enable-fast-install' to `configure'. |
| |
| `shared' |
| Change the default behaviour for `LT_INIT' to enable shared |
| libraries. This is the default on all systems where Libtool |
| knows how to create shared libraries. The user may still |
| override this default by specifying `--disable-shared' to |
| `configure'. |
| |
| `disable-shared' |
| Change the default behaviour for `LT_INIT' to disable shared |
| libraries. The user may still override this default by |
| specifying `--enable-shared' to `configure'. |
| |
| `static' |
| Change the default behaviour for `LT_INIT' to enable static |
| libraries. This is the default on all systems where shared |
| libraries have been disabled for some reason, and on most |
| systems where shared libraries have been enabled. If shared |
| libraries are enabled, the user may still override this |
| default by specifying `--disable-static' to `configure'. |
| |
| `disable-static' |
| Change the default behaviour for `LT_INIT' to disable static |
| libraries. The user may still override this default by |
| specifying `--enable-static' to `configure'. |
| |
| `pic-only' |
| Change the default behaviour for `libtool' to try to use only |
| PIC objects. The user may still override this default by |
| specifying `--without-pic' to `configure'. |
| |
| `no-pic' |
| Change the default behaviour of `libtool' to try to use only |
| non-PIC objects. The user may still override this default by |
| specifying `--with-pic' to `configure'. |
| |
| |
| |
| -- Macro: LT_LANG (LANGUAGE) |
| Enable `libtool' support for the language given if it has not yet |
| already been enabled. Languages accepted are "C++", "Fortran 77", |
| "Java", "Go", and "Windows Resource". |
| |
| If Autoconf language support macros such as `AC_PROG_CXX' are used |
| in your `configure.ac', Libtool language support will automatically |
| be enabled. |
| |
| Conversely using `LT_LANG' to enable language support for Libtool |
| will automatically enable Autoconf language support as well. |
| |
| Both of the following examples are therefore valid ways of adding |
| C++ language support to Libtool. |
| |
| LT_INIT |
| LT_LANG([C++]) |
| |
| LT_INIT |
| AC_PROG_CXX |
| |
| |
| -- Macro: AC_LIBTOOL_DLOPEN |
| This macro is deprecated, the `dlopen' option to `LT_INIT' should |
| be used instead. |
| |
| -- Macro: AC_LIBTOOL_WIN32_DLL |
| This macro is deprecated, the `win32-dll' option to `LT_INIT' |
| should be used instead. |
| |
| -- Macro: AC_DISABLE_FAST_INSTALL |
| This macro is deprecated, the `disable-fast-install' option to |
| `LT_INIT' should be used instead. |
| |
| -- Macro: AC_DISABLE_SHARED |
| -- Macro: AM_DISABLE_SHARED |
| Change the default behaviour for `LT_INIT' to disable shared |
| libraries. The user may still override this default by specifying |
| `--enable-shared'. The option `disable-shared' to `LT_INIT' is a |
| shorthand for this. `AM_DISABLE_SHARED' is a deprecated alias for |
| `AC_DISABLE_SHARED'. |
| |
| -- Macro: AC_ENABLE_SHARED |
| -- Macro: AM_ENABLE_SHARED |
| Change the default behaviour for `LT_INIT' to enable shared |
| libraries. This is the default on all systems where Libtool knows |
| how to create shared libraries. The user may still override this |
| default by specifying `--disable-shared'. The option `shared' to |
| `LT_INIT' is a shorthand for this. `AM_ENABLE_SHARED' is a |
| deprecated alias for `AC_ENABLE_SHARED'. |
| |
| -- Macro: AC_DISABLE_STATIC |
| -- Macro: AM_DISABLE_STATIC |
| Change the default behaviour for `LT_INIT' to disable static |
| libraries. The user may still override this default by specifying |
| `--enable-static'. The option `disable-static' to `LT_INIT' is a |
| shorthand for this. `AM_DISABLE_STATIC' is a deprecated alias for |
| `AC_DISABLE_STATIC'. |
| |
| -- Macro: AC_ENABLE_STATIC |
| -- Macro: AM_ENABLE_STATIC |
| Change the default behaviour for `LT_INIT' to enable static |
| libraries. This is the default on all systems where shared |
| libraries have been disabled for some reason, and on most systems |
| where shared libraries have been enabled. If shared libraries are |
| enabled, the user may still override this default by specifying |
| `--disable-static'. The option `static' to `LT_INIT' is a |
| shorthand for this. `AM_ENABLE_STATIC' is a deprecated alias for |
| `AC_ENABLE_STATIC'. |
| |
| The tests in `LT_INIT' also recognize the following environment |
| variables: |
| |
| -- Variable: CC |
| The C compiler that will be used by the generated `libtool'. If |
| this is not set, `LT_INIT' will look for `gcc' or `cc'. |
| |
| -- Variable: CFLAGS |
| Compiler flags used to generate standard object files. If this is |
| not set, `LT_INIT' will not use any such flags. It affects only |
| the way `LT_INIT' runs tests, not the produced `libtool'. |
| |
| -- Variable: CPPFLAGS |
| C preprocessor flags. If this is not set, `LT_INIT' will not use |
| any such flags. It affects only the way `LT_INIT' runs tests, not |
| the produced `libtool'. |
| |
| -- Variable: LD |
| The system linker to use (if the generated `libtool' requires one). |
| If this is not set, `LT_INIT' will try to find out what is the |
| linker used by `CC'. |
| |
| -- Variable: LDFLAGS |
| The flags to be used by `libtool' when it links a program. If |
| this is not set, `LT_INIT' will not use any such flags. It |
| affects only the way `LT_INIT' runs tests, not the produced |
| `libtool'. |
| |
| -- Variable: LIBS |
| The libraries to be used by `LT_INIT' when it links a program. If |
| this is not set, `LT_INIT' will not use any such flags. It |
| affects only the way `LT_INIT' runs tests, not the produced |
| `libtool'. |
| |
| -- Variable: NM |
| Program to use rather than checking for `nm'. |
| |
| -- Variable: RANLIB |
| Program to use rather than checking for `ranlib'. |
| |
| -- Variable: LN_S |
| A command that creates a link of a program, a soft-link if |
| possible, a hard-link otherwise. `LT_INIT' will check for a |
| suitable program if this variable is not set. |
| |
| -- Variable: DLLTOOL |
| Program to use rather than checking for `dlltool'. Only meaningful |
| for Cygwin/MS-Windows. |
| |
| -- Variable: OBJDUMP |
| Program to use rather than checking for `objdump'. Only meaningful |
| for Cygwin/MS-Windows. |
| |
| -- Variable: AS |
| Program to use rather than checking for `as'. Only used on |
| Cygwin/MS-Windows at the moment. |
| |
| -- Variable: MANIFEST_TOOL |
| Program to use rather than checking for `mt', the Manifest Tool. |
| Only used on Cygwin/MS-Windows at the moment. |
| |
| With 1.3 era libtool, if you wanted to know any details of what |
| libtool had discovered about your architecture and environment, you had |
| to run the script with `--config' and grep through the results. This |
| idiom was supported up to and including 1.5.x era libtool, where it was |
| possible to call the generated libtool script from `configure.ac' as |
| soon as `LT_INIT' had completed. However, one of the features of |
| libtool 1.4 was that the libtool configuration was migrated out of a |
| separate `ltconfig' file, and added to the `LT_INIT' macro (nee |
| `AC_PROG_LIBTOOL'), so the results of the configuration tests were |
| available directly to code in `configure.ac', rendering the call out to |
| the generated libtool script obsolete. |
| |
| Starting with libtool 2.0, the multipass generation of the libtool |
| script has been consolidated into a single `config.status' pass, which |
| happens after all the code in `configure.ac' has completed. The |
| implication of this is that the libtool script does not exist during |
| execution of code from `configure.ac', and so obviously it cannot be |
| called for `--config' details anymore. If you are upgrading projects |
| that used this idiom to libtool 2.0 or newer, you should replace those |
| calls with direct references to the equivalent Autoconf shell variables |
| that are set by the configure time tests before being passed to |
| `config.status' for inclusion in the generated libtool script. |
| |
| -- Macro: LT_OUTPUT |
| By default, the configured `libtool' script is generated by the |
| call to `AC_OUTPUT' command, and there is rarely any need to use |
| `libtool' from `configure'. However, sometimes it is necessary to |
| run configure time compile and link tests using `libtool'. You |
| can add `LT_OUTPUT' to your `configure.ac' any time after |
| `LT_INIT' and any `LT_LANG' calls; that done, `libtool' will be |
| created by a specially generated `config.lt' file, and available |
| for use in later tests. |
| |
| Also, when `LT_OUTPUT' is used, for backwards compatibility with |
| Automake regeneration rules, `config.status' will call `config.lt' |
| to regenerate `libtool', rather than generating the file itself. |
| |
| When you invoke the `libtoolize' program (*note Invoking |
| libtoolize::), it will tell you where to find a definition of |
| `LT_INIT'. If you use Automake, the `aclocal' program will |
| automatically add `LT_INIT' support to your `configure' script when it |
| sees the invocation of `LT_INIT' in `configure.ac'. |
| |
| Because of these changes, and the runtime version compatibility |
| checks Libtool now executes, we now advise *against* including a copy of |
| `libtool.m4' (and brethren) in `acinclude.m4'. Instead, you should set |
| your project macro directory with `AC_CONFIG_MACRO_DIR'. When you |
| `libtoolize' your project, a copy of the relevant macro definitions |
| will be placed in your `AC_CONFIG_MACRO_DIR', where `aclocal' can |
| reference them directly from `aclocal.m4'. |
| |
| ---------- Footnotes ---------- |
| |
| (1) `LT_INIT' requires that you define the `Makefile' variable |
| `top_builddir' in your `Makefile.in'. Automake does this |
| automatically, but Autoconf users should set it to the relative path to |
| the top of your build directory (`../..', for example). |
| |
| |
| File: libtool.info, Node: Configure notes, Prev: LT_INIT, Up: Configuring |
| |
| 5.4.2 Platform-specific configuration notes |
| ------------------------------------------- |
| |
| While Libtool tries to hide as many platform-specific features as |
| possible, some have to be taken into account when configuring either |
| the Libtool package or a libtoolized package. |
| |
| * You currently need GNU make to build the Libtool package itself. |
| |
| * On AIX there are two different styles of shared linking, one in |
| which symbols are bound at link-time and one in which symbols are |
| bound at runtime only, similar to ELF. In case of doubt use |
| `LDFLAGS=-Wl,-brtl' for the latter style. |
| |
| * On AIX, native tools are to be preferred over binutils; especially |
| for C++ code, if using the AIX Toolbox GCC 4.0 and binutils, |
| configure with `AR=/usr/bin/ar LD=/usr/bin/ld NM='/usr/bin/nm -B''. |
| |
| * On AIX, the `/bin/sh' is very slow due to its inefficient handling |
| of here-documents. A modern shell is preferable: |
| CONFIG_SHELL=/bin/bash; export $CONFIG_SHELL |
| $CONFIG_SHELL ./configure [...] |
| |
| * For C++ code with templates, it may be necessary to specify the |
| way the compiler will generate the instantiations. For Portland |
| pgCC version5, use `CXX='pgCC --one_instantiation_per_object'' and |
| avoid parallel `make'. |
| |
| * On Darwin, for C++ code with templates you need two level shared |
| libraries. Libtool builds these by default if |
| `MACOSX_DEPLOYMENT_TARGET' is set to 10.3 or later at `configure' |
| time. See `rdar://problem/4135857' for more information on this |
| issue. |
| |
| * The default shell on UNICOS 9, a ksh 88e variant, is too buggy to |
| correctly execute the libtool script. Users are advised to |
| install a modern shell such as GNU bash. |
| |
| * Some HP-UX `sed' programs are horribly broken, and cannot handle |
| libtool's requirements, so users may report unusual problems. |
| There is no workaround except to install a working `sed' (such as |
| GNU sed) on these systems. |
| |
| * The vendor-distributed NCR MP-RAS `cc' programs emits copyright on |
| standard error that confuse tests on size of `conftest.err'. The |
| workaround is to specify `CC' when run configure with `CC='cc |
| -Hnocopyr''. |
| |
| * Any earlier DG/UX system with ELF executables, such as R3.10 or |
| R4.10, is also likely to work, but hasn't been explicitly tested. |
| |
| * On Reliant Unix libtool has only been tested with the Siemens |
| C-compiler and an old version of `gcc' provided by Marco Walther. |
| |
| * `libtool.m4', `ltdl.m4' and the `configure.ac' files are marked to |
| use autoconf-mode, which is distributed with GNU Emacs 21, |
| Autoconf itself, and all recent releases of XEmacs. |
| |
| * When building on some GNU/Linux systems for multilib targets |
| `libtool' sometimes guesses the wrong paths that the linker and |
| dynamic linker search by default. If this occurs, you may override |
| libtool's guesses at `configure' time by setting the `autoconf' |
| cache variables `lt_cv_sys_lib_search_path_spec' and |
| `lt_cv_sys_lib_dlsearch_path_spec' respectively to the correct |
| search paths. |
| |
| |
| |
| File: libtool.info, Node: Distributing, Next: Static-only libraries, Prev: Configuring, Up: Integrating libtool |
| |
| 5.5 Including libtool in your package |
| ===================================== |
| |
| In order to use libtool, you need to include the following files with |
| your package: |
| |
| `config.guess' |
| Attempt to guess a canonical system name. |
| |
| `config.sub' |
| Canonical system name validation subroutine script. |
| |
| `install-sh' |
| BSD-compatible `install' replacement script. |
| |
| `ltmain.sh' |
| A generic script implementing basic libtool functionality. |
| |
| Note that the libtool script itself should _not_ be included with |
| your package. *Note Configuring::. |
| |
| You should use the `libtoolize' program, rather than manually |
| copying these files into your package. |
| |
| * Menu: |
| |
| * Invoking libtoolize:: `libtoolize' command line options. |
| * Autoconf and LTLIBOBJS:: Autoconf automates LTLIBOBJS generation. |
| |
| |
| File: libtool.info, Node: Invoking libtoolize, Next: Autoconf and LTLIBOBJS, Up: Distributing |
| |
| 5.5.1 Invoking `libtoolize' |
| --------------------------- |
| |
| The `libtoolize' program provides a standard way to add libtool support |
| to your package. In the future, it may implement better usage |
| checking, or other features to make libtool even easier to use. |
| |
| The `libtoolize' program has the following synopsis: |
| |
| libtoolize [OPTION]... |
| |
| and accepts the following options: |
| |
| `--copy' |
| `-c' |
| Copy files from the libtool data directory rather than creating |
| symlinks. |
| |
| `--debug' |
| Dump a trace of shell script execution to standard output. This |
| produces a lot of output, so you may wish to pipe it to `less' (or |
| `more') or redirect to a file. |
| |
| `--dry-run' |
| `-n' |
| Don't run any commands that modify the file system, just print them |
| out. |
| |
| `--force' |
| `-f' |
| Replace existing libtool files. By default, `libtoolize' won't |
| overwrite existing files. |
| |
| `--help' |
| Display a help message and exit. |
| |
| `--ltdl [TARGET-DIRECTORY-NAME]' |
| Install libltdl in the TARGET-DIRECTORY-NAME subdirectory of your |
| package. Normally, the directory is extracted from the argument |
| to `LT_CONFIG_LTDL_DIR' in `configure.ac', though you can also |
| specify a subdirectory name here if you are not using Autoconf for |
| example. If `libtoolize' can't determine the target directory, |
| `libltdl' is used as the default. |
| |
| `--no-warn' |
| Normally, Libtoolize tries to diagnose use of deprecated libtool |
| macros and other stylistic issues. If you are deliberately using |
| outdated calling conventions, this option prevents Libtoolize from |
| explaining how to update your project's Libtool conventions. |
| |
| `--nonrecursive' |
| If passed in conjunction with `--ltdl', this option will cause the |
| `libltdl' installed by `libtoolize' to be set up for use with a |
| non-recursive `automake' build. To make use of it, you will need |
| to add the following to the `Makefile.am' of the parent project: |
| |
| ## libltdl/Makefile.inc appends to the following variables |
| ## so we set them here before including it: |
| BUILT_SOURCES = |
| |
| AM_CPPFLAGS = |
| AM_LDFLAGS = |
| |
| include_HEADERS = |
| noinst_LTLIBRARIES = |
| lib_LTLIBRARIES = |
| EXTRA_LTLIBRARIES = |
| |
| EXTRA_DIST = |
| |
| CLEANFILES = |
| MOSTLYCLEANFILES = |
| |
| include libltdl/Makefile.inc |
| |
| |
| `--quiet' |
| `-q' |
| Work silently. `libtoolize --quiet' is used by GNU Automake to |
| add libtool files to your package if necessary. |
| |
| `--recursive' |
| If passed in conjunction with `--ltdl', this option will cause the |
| `libtoolize' installed `libltdl' to be set up for use with a |
| recursive `automake' build. To make use of it, you will need to |
| adjust the parent project's `configure.ac': |
| |
| AC_CONFIG_FILES([libltdl/Makefile]) |
| |
| and `Makefile.am': |
| |
| SUBDIRS += libltdl |
| |
| `--subproject' |
| If passed in conjunction with `--ltdl', this option will cause the |
| `libtoolize' installed `libltdl' to be set up for independent |
| configuration and compilation as a self-contained subproject. To |
| make use of it, you should arrange for your build to call |
| `libltdl/configure', and then run `make' in the `libltdl' |
| directory (or the subdirectory you put libltdl into). If your |
| project uses Autoconf, you can use the supplied `LT_WITH_LTDL' |
| macro, or else call `AC_CONFIG_SUBDIRS' directly. |
| |
| Previous releases of `libltdl' built exclusively in this mode, but |
| now it is the default mode both for backwards compatibility and |
| because, for example, it is suitable for use in projects that wish |
| to use `libltdl', but not use the Autotools for their own build |
| process. |
| |
| `--verbose' |
| `-v' |
| Work noisily! Give a blow by blow account of what `libtoolize' is |
| doing. |
| |
| `--version' |
| Print `libtoolize' version information and exit. |
| |
| Sometimes it can be useful to pass options to `libtoolize' even |
| though it is called by another program, such as `autoreconf'. A |
| limited number of options are parsed from the environment variable |
| `LIBTOOLIZE_OPTIONS': currently `--debug', `--no-warn', `--quiet' and |
| `--verbose'. Multiple options passed in `LIBTOOLIZE_OPTIONS' must be |
| separated with a space, comma or a colon. |
| |
| By default, a warning is issued for unknown options found in |
| `LIBTOOLIZE_OPTIONS' unless the first such option is `--no-warn'. |
| Where `libtoolize' has always quit on receipt of an unknown option at |
| the command line, this and all previous releases of `libtoolize' will |
| continue unabated whatever the content of `LIBTOOLIZE_OPTIONS' (modulo |
| some possible warning messages). |
| |
| trick$ LIBTOOLIZE_OPTIONS=--no-warn,--quiet autoreconf --install |
| |
| If `libtoolize' detects an explicit call to `AC_CONFIG_MACRO_DIR' |
| (*note The Autoconf Manual: (autoconf)Input.) in your `configure.ac', |
| it will put the Libtool macros in the specified directory. |
| |
| In the future other Autotools will automatically check the contents |
| of `AC_CONFIG_MACRO_DIR', but at the moment it is more portable to add |
| the macro directory to `ACLOCAL_AMFLAGS' in `Makefile.am', which is |
| where the tools currently look. If `libtoolize' doesn't see |
| `AC_CONFIG_MACRO_DIR', it too will honour the first `-I' argument in |
| `ACLOCAL_AMFLAGS' when choosing a directory to store libtool |
| configuration macros in. It is perfectly sensible to use both |
| `AC_CONFIG_MACRO_DIR' and `ACLOCAL_AMFLAGS', as long as they are kept |
| in synchronisation. |
| |
| ACLOCAL_AMFLAGS = -I m4 |
| |
| When you bootstrap your project with `aclocal', then you will need |
| to explicitly pass the same macro directory with `aclocal''s `-I' flag: |
| |
| trick$ aclocal -I m4 |
| |
| If `libtoolize' detects an explicit call to `AC_CONFIG_AUX_DIR' |
| (*note The Autoconf Manual: (autoconf)Input.) in your `configure.ac', it |
| will put the other support files in the specified directory. Otherwise |
| they too end up in the project root directory. |
| |
| Unless `--no-warn' is passed, `libtoolize' displays hints for adding |
| libtool support to your package, as well. |
| |
| |
| File: libtool.info, Node: Autoconf and LTLIBOBJS, Prev: Invoking libtoolize, Up: Distributing |
| |
| 5.5.2 Autoconf and `LTLIBOBJS' |
| ------------------------------ |
| |
| People used to add code like the following to their `configure.ac': |
| |
| LTLIBOBJS=`echo "$LIBOBJS" | sed 's/\.[^.]* /.lo /g;s/\.[^.]*$/.lo/'` |
| AC_SUBST([LTLIBOBJS]) |
| |
| This is no longer required (since Autoconf 2.54), and doesn't take |
| Automake's deansification support into account either, so doesn't work |
| correctly even with ancient Autoconfs! |
| |
| Provided you are using a recent (2.54 or better) incarnation of |
| Autoconf, the call to `AC_OUTPUT' takes care of setting `LTLIBOBJS' up |
| correctly, so you can simply delete such snippets from your |
| `configure.ac' if you had them. |
| |
| |
| File: libtool.info, Node: Static-only libraries, Prev: Distributing, Up: Integrating libtool |
| |
| 5.6 Static-only libraries |
| ========================= |
| |
| When you are developing a package, it is often worthwhile to configure |
| your package with the `--disable-shared' flag, or to override the |
| defaults for `LT_INIT' by using the `disable-shared' option (*note The |
| `LT_INIT' macro: LT_INIT.). This prevents libtool from building shared |
| libraries, which has several advantages: |
| |
| * compilation is twice as fast, which can speed up your development |
| cycle, |
| |
| * debugging is easier because you don't need to deal with any |
| complexities added by shared libraries, and |
| |
| * you can see how libtool behaves on static-only platforms. |
| |
| You may want to put a small note in your package `README' to let |
| other developers know that `--disable-shared' can save them time. The |
| following example note is taken from the GIMP(1) distribution `README': |
| |
| The GIMP uses GNU Libtool in order to build shared libraries on a |
| variety of systems. While this is very nice for making usable |
| binaries, it can be a pain when trying to debug a program. For that |
| reason, compilation of shared libraries can be turned off by |
| specifying the `--disable-shared' option to `configure'. |
| |
| ---------- Footnotes ---------- |
| |
| (1) GNU Image Manipulation Program, for those who haven't taken the |
| plunge. See `http://www.gimp.org/'. |
| |
| |
| File: libtool.info, Node: Other languages, Next: Versioning, Prev: Integrating libtool, Up: Top |
| |
| 6 Using libtool with other languages |
| ************************************ |
| |
| Libtool was first implemented in order to add support for writing shared |
| libraries in the C language. However, over time, libtool is being |
| integrated with other languages, so that programmers are free to reap |
| the benefits of shared libraries in their favorite programming language. |
| |
| This chapter describes how libtool interacts with other languages, |
| and what special considerations you need to make if you do not use C. |
| |
| * Menu: |
| |
| * C++ libraries:: Writing libraries for C++ |
| * Tags:: Tags |
| |
| |
| File: libtool.info, Node: C++ libraries, Next: Tags, Up: Other languages |
| |
| 6.1 Writing libraries for C++ |
| ============================= |
| |
| Creating libraries of C++ code should be a fairly straightforward |
| process, because its object files differ from C ones in only three ways: |
| |
| 1. Because of name mangling, C++ libraries are only usable by the C++ |
| compiler that created them. This decision was made by the |
| designers of C++ in order to protect users from conflicting |
| implementations of features such as constructors, exception |
| handling, and RTTI. |
| |
| 2. On some systems, the C++ compiler must take special actions for the |
| dynamic linker to run dynamic (i.e., run-time) initializers. This |
| means that we should not call `ld' directly to link such |
| libraries, and we should use the C++ compiler instead. |
| |
| 3. C++ compilers will link some Standard C++ library in by default, |
| but libtool does not know which are these libraries, so it cannot |
| even run the inter-library dependence analyzer to check how to |
| link it in. Therefore, running `ld' to link a C++ program or |
| library is deemed to fail. |
| |
| Because of these three issues, Libtool has been designed to always |
| use the C++ compiler to compile and link C++ programs and libraries. In |
| some instances the `main()' function of a program must also be compiled |
| with the C++ compiler for static C++ objects to be properly initialized. |
| |
| |
| File: libtool.info, Node: Tags, Prev: C++ libraries, Up: Other languages |
| |
| 6.2 Tags |
| ======== |
| |
| Libtool supports multiple languages through the use of tags. |
| Technically a tag corresponds to a set of configuration variables |
| associated with a language. These variables tell `libtool' how it |
| should create objects and libraries for each language. |
| |
| Tags are defined at `configure'-time for each language activated in |
| the package (see `LT_LANG' in *note LT_INIT::). Here is the |
| correspondence between language names and tags names. |
| |
| Language name Tag name |
| C CC |
| C++ CXX |
| Java GCJ |
| Fortran 77 F77 |
| Fortran FC |
| Go GO |
| Windows Resource RC |
| |
| `libtool' tries to automatically infer which tag to use from the |
| compiler command being used to compile or link. If it can't infer a |
| tag, then it defaults to the configuration for the `C' language. |
| |
| The tag can also be specified using `libtool''s `--tag=TAG' option |
| (*note Invoking libtool::). It is a good idea to do so in `Makefile' |
| rules, because that will allow users to substitute the compiler without |
| relying on `libtool' inference heuristics. When no tag is specified, |
| `libtool' will default to `CC'; this tag always exists. |
| |
| Finally, the set of tags available in a particular project can be |
| retrieved by tracing for the `LT_SUPPORTED_TAG' macro (*note Trace |
| interface::). |
| |
| |
| File: libtool.info, Node: Versioning, Next: Library tips, Prev: Other languages, Up: Top |
| |
| 7 Library interface versions |
| **************************** |
| |
| The most difficult issue introduced by shared libraries is that of |
| creating and resolving runtime dependencies. Dependencies on programs |
| and libraries are often described in terms of a single name, such as |
| `sed'. So, one may say "libtool depends on sed," and that is good |
| enough for most purposes. |
| |
| However, when an interface changes regularly, we need to be more |
| specific: "Gnus 5.1 requires Emacs 19.28 or above." Here, the |
| description of an interface consists of a name, and a "version number." |
| |
| Even that sort of description is not accurate enough for some |
| purposes. What if Emacs 20 changes enough to break Gnus 5.1? |
| |
| The same problem exists in shared libraries: we require a formal |
| version system to describe the sorts of dependencies that programs have |
| on shared libraries, so that the dynamic linker can guarantee that |
| programs are linked only against libraries that provide the interface |
| they require. |
| |
| * Menu: |
| |
| * Interfaces:: What are library interfaces? |
| * Libtool versioning:: Libtool's versioning system. |
| * Updating version info:: Changing version information before releases. |
| * Release numbers:: Breaking binary compatibility for aesthetics. |
| |
| |
| File: libtool.info, Node: Interfaces, Next: Libtool versioning, Up: Versioning |
| |
| 7.1 What are library interfaces? |
| ================================ |
| |
| Interfaces for libraries may be any of the following (and more): |
| |
| * global variables: both names and types |
| |
| * global functions: argument types and number, return types, and |
| function names |
| |
| * standard input, standard output, standard error, and file formats |
| |
| * sockets, pipes, and other inter-process communication protocol |
| formats |
| |
| Note that static functions do not count as interfaces, because they |
| are not directly available to the user of the library. |
| |
| |
| File: libtool.info, Node: Libtool versioning, Next: Updating version info, Prev: Interfaces, Up: Versioning |
| |
| 7.2 Libtool's versioning system |
| =============================== |
| |
| Libtool has its own formal versioning system. It is not as flexible as |
| some, but it is definitely the simplest of the more powerful versioning |
| systems. |
| |
| Think of a library as exporting several sets of interfaces, |
| arbitrarily represented by integers. When a program is linked against |
| a library, it may use any subset of those interfaces. |
| |
| Libtool's description of the interfaces that a program uses is |
| simple: it encodes the least and the greatest interface numbers in the |
| resulting binary (FIRST-INTERFACE, LAST-INTERFACE). |
| |
| The dynamic linker is guaranteed that if a library supports _every_ |
| interface number between FIRST-INTERFACE and LAST-INTERFACE, then the |
| program can be relinked against that library. |
| |
| Note that this can cause problems because libtool's compatibility |
| requirements are actually stricter than is necessary. |
| |
| Say `libhello' supports interfaces 5, 16, 17, 18, and 19, and that |
| libtool is used to link `test' against `libhello'. |
| |
| Libtool encodes the numbers 5 and 19 in `test', and the dynamic |
| linker will only link `test' against libraries that support _every_ |
| interface between 5 and 19. So, the dynamic linker refuses to link |
| `test' against `libhello'! |
| |
| In order to eliminate this problem, libtool only allows libraries to |
| declare consecutive interface numbers. So, `libhello' can declare at |
| most that it supports interfaces 16 through 19. Then, the dynamic |
| linker will link `test' against `libhello'. |
| |
| So, libtool library versions are described by three integers: |
| |
| CURRENT |
| The most recent interface number that this library implements. |
| |
| REVISION |
| The implementation number of the CURRENT interface. |
| |
| AGE |
| The difference between the newest and oldest interfaces that this |
| library implements. In other words, the library implements all the |
| interface numbers in the range from number `CURRENT - AGE' to |
| `CURRENT'. |
| |
| If two libraries have identical CURRENT and AGE numbers, then the |
| dynamic linker chooses the library with the greater REVISION number. |
| |
| |
| File: libtool.info, Node: Updating version info, Next: Release numbers, Prev: Libtool versioning, Up: Versioning |
| |
| 7.3 Updating library version information |
| ======================================== |
| |
| If you want to use libtool's versioning system, then you must specify |
| the version information to libtool using the `-version-info' flag |
| during link mode (*note Link mode::). |
| |
| This flag accepts an argument of the form |
| `CURRENT[:REVISION[:AGE]]'. So, passing `-version-info 3:12:1' sets |
| CURRENT to 3, REVISION to 12, and AGE to 1. |
| |
| If either REVISION or AGE are omitted, they default to 0. Also note |
| that AGE must be less than or equal to the CURRENT interface number. |
| |
| Here are a set of rules to help you update your library version |
| information: |
| |
| 1. Start with version information of `0:0:0' for each libtool library. |
| |
| 2. Update the version information only immediately before a public |
| release of your software. More frequent updates are unnecessary, |
| and only guarantee that the current interface number gets larger |
| faster. |
| |
| 3. If the library source code has changed at all since the last |
| update, then increment REVISION (`C:R:A' becomes `C:r+1:A'). |
| |
| 4. If any interfaces have been added, removed, or changed since the |
| last update, increment CURRENT, and set REVISION to 0. |
| |
| 5. If any interfaces have been added since the last public release, |
| then increment AGE. |
| |
| 6. If any interfaces have been removed or changed since the last |
| public release, then set AGE to 0. |
| |
| *_Never_* try to set the interface numbers so that they correspond |
| to the release number of your package. This is an abuse that only |
| fosters misunderstanding of the purpose of library versions. Instead, |
| use the `-release' flag (*note Release numbers::), but be warned that |
| every release of your package will not be binary compatible with any |
| other release. |
| |
| The following explanation may help to understand the above rules a |
| bit better: consider that there are three possible kinds of reactions |
| from users of your library to changes in a shared library: |
| |
| 1. Programs using the previous version may use the new version as |
| drop-in replacement, and programs using the new version can also |
| work with the previous one. In other words, no recompiling nor |
| relinking is needed. In this case, bump REVISION only, don't touch |
| CURRENT nor AGE. |
| |
| 2. Programs using the previous version may use the new version as |
| drop-in replacement, but programs using the new version may use |
| APIs not present in the previous one. In other words, a program |
| linking against the new version may fail with "unresolved symbols" |
| if linking against the old version at runtime: set REVISION to 0, |
| bump CURRENT and AGE. |
| |
| 3. Programs may need to be changed, recompiled, relinked in order to |
| use the new version. Bump CURRENT, set REVISION and AGE to 0. |
| |
| In the above description, _programs_ using the library in question may |
| also be replaced by other libraries using it. |
| |
| |
| File: libtool.info, Node: Release numbers, Prev: Updating version info, Up: Versioning |
| |
| 7.4 Managing release information |
| ================================ |
| |
| Often, people want to encode the name of the package release into the |
| shared library so that it is obvious to the user which package their |
| programs are linked against. This convention is used especially on |
| GNU/Linux: |
| |
| trick$ ls /usr/lib/libbfd* |
| /usr/lib/libbfd.a /usr/lib/libbfd.so.2.7.0.2 |
| /usr/lib/libbfd.so |
| trick$ |
| |
| On `trick', `/usr/lib/libbfd.so' is a symbolic link to |
| `libbfd.so.2.7.0.2', which was distributed as a part of |
| `binutils-2.7.0.2'. |
| |
| Unfortunately, this convention conflicts directly with libtool's |
| idea of library interface versions, because the library interface |
| rarely changes at the same time that the release number does, and the |
| library suffix is never the same across all platforms. |
| |
| So, in order to accommodate both views, you can use the `-release' |
| flag in order to set release information for libraries for which you do |
| not want to use `-version-info'. For the `libbfd' example, the next |
| release that uses libtool should be built with `-release 2.9.0', which |
| will produce the following files on GNU/Linux: |
| |
| trick$ ls /usr/lib/libbfd* |
| /usr/lib/libbfd-2.9.0.so /usr/lib/libbfd.a |
| /usr/lib/libbfd.so |
| trick$ |
| |
| In this case, `/usr/lib/libbfd.so' is a symbolic link to |
| `libbfd-2.9.0.so'. This makes it obvious that the user is dealing with |
| `binutils-2.9.0', without compromising libtool's idea of interface |
| versions. |
| |
| Note that this option causes a modification of the library name, so |
| do not use it unless you want to break binary compatibility with any |
| past library releases. In general, you should only use `-release' for |
| package-internal libraries or for ones whose interfaces change very |
| frequently. |
| |
| |
| File: libtool.info, Node: Library tips, Next: Inter-library dependencies, Prev: Versioning, Up: Top |
| |
| 8 Tips for interface design |
| *************************** |
| |
| Writing a good library interface takes a lot of practice and thorough |
| understanding of the problem that the library is intended to solve. |
| |
| If you design a good interface, it won't have to change often, you |
| won't have to keep updating documentation, and users won't have to keep |
| relearning how to use the library. |
| |
| Here is a brief list of tips for library interface design that may |
| help you in your exploits: |
| |
| Plan ahead |
| Try to make every interface truly minimal, so that you won't need |
| to delete entry points very often. |
| |
| Avoid interface changes |
| Some people love redesigning and changing entry points just for |
| the heck of it (note: _renaming_ a function is considered changing |
| an entry point). Don't be one of those people. If you must |
| redesign an interface, then try to leave compatibility functions |
| behind so that users don't need to rewrite their existing code. |
| |
| Use opaque data types |
| The fewer data type definitions a library user has access to, the |
| better. If possible, design your functions to accept a generic |
| pointer (that you can cast to an internal data type), and provide |
| access functions rather than allowing the library user to directly |
| manipulate the data. That way, you have the freedom to change the |
| data structures without changing the interface. |
| |
| This is essentially the same thing as using abstract data types and |
| inheritance in an object-oriented system. |
| |
| Use header files |
| If you are careful to document each of your library's global |
| functions and variables in header files, and include them in your |
| library source files, then the compiler will let you know if you |
| make any interface changes by accident (*note C header files::). |
| |
| Use the `static' keyword (or equivalent) whenever possible |
| The fewer global functions your library has, the more flexibility |
| you'll have in changing them. Static functions and variables may |
| change forms as often as you like... your users cannot access |
| them, so they aren't interface changes. |
| |
| Be careful with array dimensions |
| The number of elements in a global array is part of an interface, |
| even if the header just declares `extern int foo[];'. This is |
| because on i386 and some other SVR4/ELF systems, when an |
| application references data in a shared library the size of that |
| data (whatever its type) is included in the application |
| executable. If you might want to change the size of an array or |
| string then provide a pointer not the actual array. |
| |
| * Menu: |
| |
| * C header files:: How to write portable include files. |
| |
| |
| File: libtool.info, Node: C header files, Up: Library tips |
| |
| 8.1 Writing C header files |
| ========================== |
| |
| Writing portable C header files can be difficult, since they may be read |
| by different types of compilers: |
| |
| C++ compilers |
| C++ compilers require that functions be declared with full |
| prototypes, since C++ is more strongly typed than C. C functions |
| and variables also need to be declared with the `extern "C"' |
| directive, so that the names aren't mangled. *Note C++ |
| libraries::, for other issues relevant to using C++ with libtool. |
| |
| ANSI C compilers |
| ANSI C compilers are not as strict as C++ compilers, but functions |
| should be prototyped to avoid unnecessary warnings when the header |
| file is `#include'd. |
| |
| non-ANSI C compilers |
| Non-ANSI compilers will report errors if functions are prototyped. |
| |
| These complications mean that your library interface headers must use |
| some C preprocessor magic in order to be usable by each of the above |
| compilers. |
| |
| `foo.h' in the `tests/demo' subdirectory of the libtool distribution |
| serves as an example for how to write a header file that can be safely |
| installed in a system directory. |
| |
| Here are the relevant portions of that file: |
| |
| /* BEGIN_C_DECLS should be used at the beginning of your declarations, |
| so that C++ compilers don't mangle their names. Use END_C_DECLS at |
| the end of C declarations. */ |
| #undef BEGIN_C_DECLS |
| #undef END_C_DECLS |
| #ifdef __cplusplus |
| # define BEGIN_C_DECLS extern "C" { |
| # define END_C_DECLS } |
| #else |
| # define BEGIN_C_DECLS /* empty */ |
| # define END_C_DECLS /* empty */ |
| #endif |
| |
| /* PARAMS is a macro used to wrap function prototypes, so that |
| compilers that don't understand ANSI C prototypes still work, |
| and ANSI C compilers can issue warnings about type mismatches. */ |
| #undef PARAMS |
| #if defined (__STDC__) || defined (_AIX) \ |
| || (defined (__mips) && defined (_SYSTYPE_SVR4)) \ |
| || defined(WIN32) || defined(__cplusplus) |
| # define PARAMS(protos) protos |
| #else |
| # define PARAMS(protos) () |
| #endif |
| |
| These macros are used in `foo.h' as follows: |
| |
| #ifndef FOO_H |
| #define FOO_H 1 |
| |
| /* The above macro definitions. */ |
| #include "..." |
| |
| BEGIN_C_DECLS |
| |
| int foo PARAMS((void)); |
| int hello PARAMS((void)); |
| |
| END_C_DECLS |
| |
| #endif /* !FOO_H */ |
| |
| Note that the `#ifndef FOO_H' prevents the body of `foo.h' from |
| being read more than once in a given compilation. |
| |
| Also the only thing that must go outside the |
| `BEGIN_C_DECLS'/`END_C_DECLS' pair are `#include' lines. Strictly |
| speaking it is only C symbol names that need to be protected, but your |
| header files will be more maintainable if you have a single pair of |
| these macros around the majority of the header contents. |
| |
| You should use these definitions of `PARAMS', `BEGIN_C_DECLS', and |
| `END_C_DECLS' into your own headers. Then, you may use them to create |
| header files that are valid for C++, ANSI, and non-ANSI compilers(1). |
| |
| Do not be naive about writing portable code. Following the tips |
| given above will help you miss the most obvious problems, but there are |
| definitely other subtle portability issues. You may need to cope with |
| some of the following issues: |
| |
| * Pre-ANSI compilers do not always support the `void *' generic |
| pointer type, and so need to use `char *' in its place. |
| |
| * The `const', `inline' and `signed' keywords are not supported by |
| some compilers, especially pre-ANSI compilers. |
| |
| * The `long double' type is not supported by many compilers. |
| |
| ---------- Footnotes ---------- |
| |
| (1) We used to recommend `__P', `__BEGIN_DECLS' and `__END_DECLS'. |
| This was bad advice since symbols (even preprocessor macro names) that |
| begin with an underscore are reserved for the use of the compiler. |
| |
| |
| File: libtool.info, Node: Inter-library dependencies, Next: Dlopened modules, Prev: Library tips, Up: Top |
| |
| 9 Inter-library dependencies |
| **************************** |
| |
| By definition, every shared library system provides a way for |
| executables to depend on libraries, so that symbol resolution is |
| deferred until runtime. |
| |
| An "inter-library dependency" is one in which a library depends on |
| other libraries. For example, if the libtool library `libhello' uses |
| the `cos' function, then it has an inter-library dependency on `libm', |
| the math library that implements `cos'. |
| |
| Some shared library systems provide this feature in an |
| internally-consistent way: these systems allow chains of dependencies of |
| potentially infinite length. |
| |
| However, most shared library systems are restricted in that they only |
| allow a single level of dependencies. In these systems, programs may |
| depend on shared libraries, but shared libraries may not depend on other |
| shared libraries. |
| |
| In any event, libtool provides a simple mechanism for you to declare |
| inter-library dependencies: for every library `libNAME' that your own |
| library depends on, simply add a corresponding `-lNAME' option to the |
| link line when you create your library. To make an example of our |
| `libhello' that depends on `libm': |
| |
| burger$ libtool --mode=link gcc -g -O -o libhello.la foo.lo hello.lo \ |
| -rpath /usr/local/lib -lm |
| burger$ |
| |
| When you link a program against `libhello', you don't need to |
| specify the same `-l' options again: libtool will do that for you, in |
| order to guarantee that all the required libraries are found. This |
| restriction is only necessary to preserve compatibility with static |
| library systems and simple dynamic library systems. |
| |
| Some platforms, such as Windows, do not even allow you this |
| flexibility. In order to build a shared library, it must be entirely |
| self-contained or it must have dependencies known at link time (that is, |
| have references only to symbols that are found in the `.lo' files or |
| the specified `-l' libraries), and you need to specify the |
| `-no-undefined' flag. By default, libtool builds only static libraries |
| on these kinds of platforms. |
| |
| The simple-minded inter-library dependency tracking code of libtool |
| releases prior to 1.2 was disabled because it was not clear when it was |
| possible to link one library with another, and complex failures would |
| occur. A more complex implementation of this concept was re-introduced |
| before release 1.3, but it has not been ported to all platforms that |
| libtool supports. The default, conservative behavior is to avoid |
| linking one library with another, introducing their inter-dependencies |
| only when a program is linked with them. |
| |
| |
| File: libtool.info, Node: Dlopened modules, Next: Using libltdl, Prev: Inter-library dependencies, Up: Top |
| |
| 10 Dlopened modules |
| ******************* |
| |
| It can sometimes be confusing to discuss "dynamic linking", because the |
| term is used to refer to two different concepts: |
| |
| 1. Compiling and linking a program against a shared library, which is |
| resolved automatically at run time by the dynamic linker. In this |
| process, dynamic linking is transparent to the application. |
| |
| 2. The application calling functions such as `dlopen' that load |
| arbitrary, user-specified modules at runtime. This type of dynamic |
| linking is explicitly controlled by the application. |
| |
| To mitigate confusion, this manual refers to the second type of |
| dynamic linking as "dlopening" a module. |
| |
| The main benefit to dlopening object modules is the ability to access |
| compiled object code to extend your program, rather than using an |
| interpreted language. In fact, dlopen calls are frequently used in |
| language interpreters to provide an efficient way to extend the |
| language. |
| |
| Libtool provides support for dlopened modules. However, you should |
| indicate that your package is willing to use such support, by using the |
| `LT_INIT' option `dlopen' in `configure.ac'. If this option is not |
| given, libtool will assume no dlopening mechanism is available, and |
| will try to simulate it. |
| |
| This chapter discusses how you as a dlopen application developer |
| might use libtool to generate dlopen-accessible modules. |
| |
| * Menu: |
| |
| * Building modules:: Creating dlopenable objects and libraries. |
| * Dlpreopening:: Dlopening that works on static platforms. |
| * Linking with dlopened modules:: Using dlopenable modules in libraries. |
| * Finding the dlname:: Choosing the right file to `dlopen'. |
| * Dlopen issues:: Unresolved problems that need your attention. |
| |
| |
| File: libtool.info, Node: Building modules, Next: Dlpreopening, Up: Dlopened modules |
| |
| 10.1 Building modules to dlopen |
| =============================== |
| |
| On some operating systems, a program symbol must be specially declared |
| in order to be dynamically resolved with the `dlsym' (or equivalent) |
| function. Libtool provides the `-export-dynamic' and `-module' link |
| flags (*note Link mode::), for you to make that declaration. You need |
| to use these flags if you are linking an application program that |
| dlopens other modules or a libtool library that will also be dlopened. |
| |
| For example, if we wanted to build a shared library, `hello', that |
| would later be dlopened by an application, we would add `-module' to |
| the other link flags: |
| |
| burger$ libtool --mode=link gcc -module -o hello.la foo.lo \ |
| hello.lo -rpath /usr/local/lib -lm |
| burger$ |
| |
| If symbols from your _executable_ are needed to satisfy unresolved |
| references in a library you want to dlopen you will have to use the flag |
| `-export-dynamic'. You should use `-export-dynamic' while linking the |
| executable that calls dlopen: |
| |
| burger$ libtool --mode=link gcc -export-dynamic -o helldl main.o |
| burger$ |
| |
| |
| File: libtool.info, Node: Dlpreopening, Next: Linking with dlopened modules, Prev: Building modules, Up: Dlopened modules |
| |
| 10.2 Dlpreopening |
| ================= |
| |
| Libtool provides special support for dlopening libtool object and |
| libtool library files, so that their symbols can be resolved _even on |
| platforms without any `dlopen' and `dlsym' functions_. |
| |
| Consider the following alternative ways of loading code into your |
| program, in order of increasing "laziness": |
| |
| 1. Linking against object files that become part of the program |
| executable, whether or not they are referenced. If an object file |
| cannot be found, then the compile time linker refuses to create |
| the executable. |
| |
| 2. Declaring a static library to the linker, so that it is searched |
| at link time in order to satisfy any undefined references in the |
| above object files. If the static library cannot be found, then |
| the compile time linker refuses to create the executable. |
| |
| 3. Declaring a shared library to the runtime linker, so that it is |
| searched at runtime in order to satisfy any undefined references |
| in the above files. If the shared library cannot be found, then |
| the dynamic linker aborts the program before it runs. |
| |
| 4. Dlopening a module, so that the application can resolve its own, |
| dynamically-computed references. If there is an error opening the |
| module, or the module is not found, then the application can |
| recover without crashing. |
| |
| Libtool emulates `-dlopen' on static platforms by linking objects |
| into the program at compile time, and creating data structures that |
| represent the program's symbol table. In order to use this feature, |
| you must declare the objects you want your application to dlopen by |
| using the `-dlopen' or `-dlpreopen' flags when you link your program |
| (*note Link mode::). |
| |
| -- Data Type: lt_dlsymlist typedef struct { const char *NAME; |
| void *ADDRESS; } lt_dlsymlist |
| The NAME attribute is a null-terminated character string of the |
| symbol name, such as `"fprintf"'. The ADDRESS attribute is a |
| generic pointer to the appropriate object, such as `&fprintf'. |
| |
| -- Variable: const lt_dlsymlist lt_preloaded_symbols[] |
| An array of `lt_dlsymlist' structures, representing all the |
| preloaded symbols linked into the program proper. For each module |
| `-dlpreopen'ed by the Libtool linked program there is an element |
| with the NAME of the module and an ADDRESS of `0', followed by all |
| symbols exported from this file. For the executable itself the |
| special name `@PROGRAM@' is used. The last element of all has a |
| NAME and ADDRESS of `0'. |
| |
| To facilitate inclusion of symbol lists into libraries, |
| `lt_preloaded_symbols' is `#define'd to a suitably unique name in |
| `ltdl.h'. |
| |
| This variable may not be declared `const' on some systems due to |
| relocation issues. |
| |
| Some compilers may allow identifiers that are not valid in ANSI C, |
| such as dollar signs. Libtool only recognizes valid ANSI C symbols (an |
| initial ASCII letter or underscore, followed by zero or more ASCII |
| letters, digits, and underscores), so non-ANSI symbols will not appear |
| in `lt_preloaded_symbols'. |
| |
| -- Function: int lt_dlpreload (const lt_dlsymlist *PRELOADED) |
| Register the list of preloaded modules PRELOADED. If PRELOADED is |
| `NULL', then all previously registered symbol lists, except the |
| list set by `lt_dlpreload_default', are deleted. Return 0 on |
| success. |
| |
| -- Function: int lt_dlpreload_default (const lt_dlsymlist *PRELOADED) |
| Set the default list of preloaded modules to PRELOADED, which |
| won't be deleted by `lt_dlpreload'. Note that this function does |
| _not_ require libltdl to be initialized using `lt_dlinit' and can |
| be used in the program to register the default preloaded modules. |
| Instead of calling this function directly, most programs will use |
| the macro `LTDL_SET_PRELOADED_SYMBOLS'. |
| |
| Return 0 on success. |
| |
| -- Macro: LTDL_SET_PRELOADED_SYMBOLS |
| Set the default list of preloaded symbols. Should be used in your |
| program to initialize libltdl's list of preloaded modules. |
| |
| #include <ltdl.h> |
| |
| int main() { |
| /* ... */ |
| LTDL_SET_PRELOADED_SYMBOLS(); |
| /* ... */ |
| } |
| |
| -- Function Type: int lt_dlpreload_callback_func (lt_dlhandle HANDLE) |
| Functions of this type can be passed to `lt_dlpreload_open', which |
| in turn will call back into a function thus passed for each |
| preloaded module that it opens. |
| |
| -- Function: int lt_dlpreload_open (const char *ORIGINATOR, |
| lt_dlpreload_callback_func *FUNC) |
| Load all of the preloaded modules for ORIGINATOR. For every |
| module opened in this way, call FUNC. |
| |
| To open all of the modules preloaded into `libhell.la' (presumably |
| from within the `libhell.a' initialisation code): |
| |
| #define preloaded_symbols lt_libhell_LTX_preloaded_symbols |
| |
| static int hell_preload_callback (lt_dlhandle handle); |
| |
| int |
| hell_init (void) |
| { |
| ... |
| if (lt_dlpreload (&preloaded_symbols) == 0) |
| { |
| lt_dlpreload_open ("libhell", preload_callback); |
| } |
| ... |
| } |
| |
| Note that to prevent clashes between multiple preloaded modules, |
| the preloaded symbols are accessed via a mangled symbol name: to |
| get the symbols preloaded into `libhell', you must prefix |
| `preloaded_symbols' with `lt_'; the originator name, `libhell' in |
| this case; and `_LTX_'. That is, |
| `lt_libhell_LTX_preloaded_symbols' here. |
| |
| |
| File: libtool.info, Node: Linking with dlopened modules, Next: Finding the dlname, Prev: Dlpreopening, Up: Dlopened modules |
| |
| 10.3 Linking with dlopened modules |
| ================================== |
| |
| When, say, an interpreter application uses dlopened modules to extend |
| the list of methods it provides, an obvious abstraction for the |
| maintainers of the interpreter is to have all methods (including the |
| built in ones supplied with the interpreter) accessed through dlopen. |
| For one thing, the dlopening functionality will be tested even during |
| routine invocations. For another, only one subsystem has to be written |
| for getting methods into the interpreter. |
| |
| The downside of this abstraction is, of course, that environments |
| that provide only static linkage can't even load the intrinsic |
| interpreter methods. Not so! We can statically link those methods by |
| *dlpreopening* them. |
| |
| Unfortunately, since platforms such as AIX and cygwin require that |
| all library symbols must be resolved at compile time, the interpreter |
| maintainers will need to provide a library to both its own dlpreopened |
| modules, and third-party modules loaded by dlopen. In itself, that is |
| not so bad, except that the interpreter too must provide those same |
| symbols otherwise it will be impossible to resolve all the symbols |
| required by the modules as they are loaded. Things are even worse if |
| the code that loads the modules for the interpreter is itself in a |
| library - and that is usually the case for any non-trivial application. |
| Modern platforms take care of this by automatically loading all of a |
| module's dependency libraries as the module is loaded (libltdl can do |
| this even on platforms that can't do it by themselves). In the end, |
| this leads to problems with duplicated symbols and prevents modules |
| from loading, and prevents the application from compiling when modules |
| are preloaded. |
| |
| ,-------------. ,------------------. ,-----------------. |
| | Interpreter |----> Module------------> Third-party | |
| `-------------' | Loader | |Dlopened Modules | |
| | | | `-----------------' |
| |,-------v--------.| | |
| || Dlpreopened || | |
| || Modules || | |
| |`----------------'| | |
| | | | | |
| |,-------v--------.| ,--------v--------. |
| ||Module Interface|| |Module Interface | |
| || Library || | Library | |
| |`----------------'| `-----------------' |
| `------------------' |
| |
| Libtool has the concept of "weak library interfaces" to circumvent |
| this problem. Recall that the code that dlopens method-provider |
| modules for the interpreter application resides in a library: All of |
| the modules and the dlopener library itself should be linked against |
| the common library that resolves the module symbols at compile time. |
| To guard against duplicate symbol definitions, and for dlpreopened |
| modules to work at all in this scenario, the dlopener library must |
| declare that it provides a weak library interface to the common symbols |
| in the library it shares with the modules. That way, when `libtool' |
| links the *Module Loader* library with some *Dlpreopened Modules* that |
| were in turn linked against the *Module Interface Library*, it knows |
| that the *Module Loader* provides an already loaded *Module Interface |
| Library* to resolve symbols for the *Dlpreopened Modules*, and doesn't |
| ask the compiler driver to link an identical *Module Interface Library* |
| dependency library too. |
| |
| In conjunction with Automake, the `Makefile.am' for the *Module |
| Loader* might look like this: |
| |
| lib_LTLIBRARIES = libinterface.la libloader.la |
| |
| libinterface_la_SOURCES = interface.c interface.h |
| libinterface_la_LDFLAGS = -version-info 3:2:1 |
| |
| libloader_la_SOURCES = loader.c |
| libloader_la_LDFLAGS = -weak libinterface.la \ |
| -version-info 3:2:1 \ |
| -dlpreopen ../modules/intrinsics.la |
| libloader_la_LIBADD = $(libinterface_la_OBJECTS) |
| |
| And the `Makefile.am' for the `intrinsics.la' module in a sibling |
| `modules' directory might look like this: |
| |
| AM_CPPFLAGS = -I$(srcdir)/../libloader |
| AM_LDFLAGS = -no-undefined -module -avoid-version \ |
| -export-dynamic |
| |
| noinst_LTLIBRARIES = intrinsics.la |
| |
| intrinsics_la_LIBADD = ../libloader/libinterface.la |
| |
| ../libloader/libinterface.la: |
| cd ../libloader && $(MAKE) $(AM_MAKEFLAGS) libinterface.la |
| |
| For a more complex example, see the sources of `libltdl' in the |
| Libtool distribution, which is built with the help of the `-weak' |
| option. |
| |
| |
| File: libtool.info, Node: Finding the dlname, Next: Dlopen issues, Prev: Linking with dlopened modules, Up: Dlopened modules |
| |
| 10.4 Finding the correct name to dlopen |
| ======================================= |
| |
| After a library has been linked with `-module', it can be dlopened. |
| Unfortunately, because of the variation in library names, your package |
| needs to determine the correct file to dlopen. |
| |
| The most straightforward and flexible implementation is to determine |
| the name at runtime, by finding the installed `.la' file, and searching |
| it for the following lines: |
| |
| # The name that we can `dlopen'. |
| dlname='DLNAME' |
| |
| If DLNAME is empty, then the library cannot be dlopened. Otherwise, |
| it gives the dlname of the library. So, if the library was installed |
| as `/usr/local/lib/libhello.la', and the DLNAME was `libhello.so.3', |
| then `/usr/local/lib/libhello.so.3' should be dlopened. |
| |
| If your program uses this approach, then it should search the |
| directories listed in the `LD_LIBRARY_PATH'(1) environment variable, as |
| well as the directory where libraries will eventually be installed. |
| Searching this variable (or equivalent) will guarantee that your |
| program can find its dlopened modules, even before installation, |
| provided you have linked them using libtool. |
| |
| ---------- Footnotes ---------- |
| |
| (1) `LIBPATH' on AIX, and `SHLIB_PATH' on HP-UX. |
| |
| |
| File: libtool.info, Node: Dlopen issues, Prev: Finding the dlname, Up: Dlopened modules |
| |
| 10.5 Unresolved dlopen issues |
| ============================= |
| |
| The following problems are not solved by using libtool's dlopen support: |
| |
| * Dlopen functions are generally only available on shared library |
| platforms. If you want your package to be portable to static |
| platforms, you have to use either libltdl (*note Using libltdl::) |
| or develop your own alternatives to dlopening dynamic code. Most |
| reasonable solutions involve writing wrapper functions for the |
| `dlopen' family, which do package-specific tricks when dlopening |
| is unsupported or not available on a given platform. |
| |
| * There are major differences in implementations of the `dlopen' |
| family of functions. Some platforms do not even use the same |
| function names (notably HP-UX, with its `shl_load' family). |
| |
| * The application developer must write a custom search function in |
| order to discover the correct module filename to supply to |
| `dlopen'. |
| |
| |
| File: libtool.info, Node: Using libltdl, Next: Trace interface, Prev: Dlopened modules, Up: Top |
| |
| 11 Using libltdl |
| **************** |
| |
| Libtool provides a small library, called `libltdl', that aims at hiding |
| the various difficulties of dlopening libraries from programmers. It |
| consists of a few headers and small C source files that can be |
| distributed with applications that need dlopening functionality. On |
| some platforms, whose dynamic linkers are too limited for a simple |
| implementation of `libltdl' services, it requires GNU DLD, or it will |
| only emulate dynamic linking with libtool's dlpreopening mechanism. |
| |
| libltdl supports currently the following dynamic linking mechanisms: |
| |
| * `dlopen' (POSIX compliant systems, GNU/Linux, etc.) |
| |
| * `shl_load' (HP-UX) |
| |
| * `LoadLibrary' (Win16 and Win32) |
| |
| * `load_add_on' (BeOS) |
| |
| * `NSAddImage' or `NSLinkModule' (Darwin and Mac OS X) |
| |
| * GNU DLD (emulates dynamic linking for static libraries) |
| |
| * libtool's dlpreopen (see *note Dlpreopening::) |
| |
| libltdl is licensed under the terms of the GNU Lesser General Public |
| License, with the following exception: |
| |
| As a special exception to the GNU Lesser General Public License, |
| if you distribute this file as part of a program or library that |
| is built using GNU Libtool, you may include it under the same |
| distribution terms that you use for the rest of that program. |
| |
| * Menu: |
| |
| * Libltdl interface:: How to use libltdl in your programs. |
| * Modules for libltdl:: Creating modules that can be `dlopen'ed. |
| * Thread Safety in libltdl:: Registering callbacks for multi-thread safety. |
| * User defined module data:: Associating data with loaded modules. |
| * Module loaders for libltdl:: Creating user defined module loaders. |
| * Distributing libltdl:: How to distribute libltdl with your package. |
| |
| |
| File: libtool.info, Node: Libltdl interface, Next: Modules for libltdl, Up: Using libltdl |
| |
| 11.1 How to use libltdl in your programs |
| ======================================== |
| |
| The libltdl API is similar to the POSIX dlopen interface, which is very |
| simple but powerful. |
| |
| To use libltdl in your program you have to include the header file |
| `ltdl.h': |
| |
| #include <ltdl.h> |
| |
| The early releases of libltdl used some symbols that violated the POSIX |
| namespace conventions. These symbols are now deprecated, and have been |
| replaced by those described here. If you have code that relies on the |
| old deprecated symbol names, defining `LT_NON_POSIX_NAMESPACE' before |
| you include `ltdl.h' provides conversion macros. Whichever set of |
| symbols you use, the new API is not binary compatible with the last, so |
| you will need to recompile your application in order to use this |
| version of libltdl. |
| |
| Note that libltdl is not well tested in a multithreaded environment, |
| though the intention is that it should work (*note Using libltdl in a |
| multi threaded environment: Thread Safety in libltdl.). It was |
| reported that GNU/Linux's glibc 2.0's `dlopen' with `RTLD_LAZY' (which |
| libltdl uses by default) is not thread-safe, but this problem is |
| supposed to be fixed in glibc 2.1. On the other hand, `RTLD_NOW' was |
| reported to introduce problems in multi-threaded applications on |
| FreeBSD. Working around these problems is left as an exercise for the |
| reader; contributions are certainly welcome. |
| |
| The following macros are defined by including `ltdl.h': |
| |
| -- Macro: LT_PATHSEP_CHAR |
| `LT_PATHSEP_CHAR' is the system-dependent path separator, that is, |
| `;' on Windows and `:' everywhere else. |
| |
| -- Macro: LT_DIRSEP_CHAR |
| If `LT_DIRSEP_CHAR' is defined, it can be used as directory |
| separator in addition to `/'. On Windows, this contains `\'. |
| |
| The following types are defined in `ltdl.h': |
| |
| -- Type: lt_dlhandle |
| `lt_dlhandle' is a module "handle". Every lt_dlopened module has |
| a handle associated with it. |
| |
| -- Type: lt_dladvise |
| `lt_dladvise' is used to control optional module loading modes. |
| If it is not used, the default mode of the underlying system module |
| loader is used. |
| |
| -- Type: lt_dlsymlist |
| `lt_dlsymlist' is a symbol list for dlpreopened modules. This |
| structure is described in *note Dlpreopening::. |
| |
| libltdl provides the following functions: |
| |
| -- Function: int lt_dlinit (void) |
| Initialize libltdl. This function must be called before using |
| libltdl and may be called several times. Return 0 on success, |
| otherwise the number of errors. |
| |
| -- Function: int lt_dlexit (void) |
| Shut down libltdl and close all modules. This function will only |
| then shut down libltdl when it was called as many times as |
| `lt_dlinit' has been successfully called. Return 0 on success, |
| otherwise the number of errors. |
| |
| -- Function: lt_dlhandle lt_dlopen (const char *FILENAME) |
| Open the module with the file name FILENAME and return a handle |
| for it. `lt_dlopen' is able to open libtool dynamic modules, |
| preloaded static modules, the program itself and native dynamic |
| modules(1). |
| |
| Unresolved symbols in the module are resolved using its dependency |
| libraries and previously dlopened modules. If the executable using |
| this module was linked with the `-export-dynamic' flag, then the |
| global symbols in the executable will also be used to resolve |
| references in the module. |
| |
| If FILENAME is `NULL' and the program was linked with |
| `-export-dynamic' or `-dlopen self', `lt_dlopen' will return a |
| handle for the program itself, which can be used to access its |
| symbols. |
| |
| If libltdl cannot find the library and the file name FILENAME does |
| not have a directory component it will additionally look in the |
| following search paths for the module (in the following order): |
| |
| 1. user-defined search path: This search path can be changed by |
| the program using the functions `lt_dlsetsearchpath', |
| `lt_dladdsearchdir' and `lt_dlinsertsearchdir'. |
| |
| 2. libltdl's search path: This search path is the value of the |
| environment variable `LTDL_LIBRARY_PATH'. |
| |
| 3. system library search path: The system dependent library |
| search path (e.g. on GNU/Linux it is `LD_LIBRARY_PATH'). |
| |
| Each search path must be a list of absolute directories separated |
| by `LT_PATHSEP_CHAR', for example, `"/usr/lib/mypkg:/lib/foo"'. |
| The directory names may not contain the path separator. |
| |
| If the same module is loaded several times, the same handle is |
| returned. If `lt_dlopen' fails for any reason, it returns `NULL'. |
| |
| -- Function: lt_dlhandle lt_dlopenext (const char *FILENAME) |
| The same as `lt_dlopen', except that it tries to append different |
| file name extensions to the file name. If the file with the file |
| name FILENAME cannot be found libltdl tries to append the |
| following extensions: |
| |
| 1. the libtool archive extension `.la' |
| |
| 2. the extension used for native dynamically loadable modules on |
| the host platform, e.g., `.so', `.sl', etc. |
| |
| This lookup strategy was designed to allow programs that don't |
| have knowledge about native dynamic libraries naming conventions |
| to be able to `dlopen' such libraries as well as libtool modules |
| transparently. |
| |
| -- Function: lt_dlhandle lt_dlopenadvise (const char *FILENAME, |
| lt_dladvise ADVISE) |
| The same as `lt_dlopen', except that it also requires an additional |
| argument which may contain additional hints to the underlying |
| system module loader. The ADVISE parameter is opaque and can only |
| be accessed with the functions documented below. |
| |
| Note that this function does not change the content of ADVISE, so |
| unlike the other calls in this API takes a direct `lt_dladvise' |
| type, and not a pointer to the same. |
| |
| -- Function: int lt_dladvise_init (lt_dladvise *ADVISE) |
| The ADVISE parameter can be used to pass hints to the module |
| loader when using `lt_dlopenadvise' to perform the loading. The |
| ADVISE parameter needs to be initialised by this function before |
| it can be used. Any memory used by ADVISE needs to be recycled |
| with `lt_dladvise_destroy' when it is no longer needed. |
| |
| On failure, `lt_dladvise_init' returns non-zero and sets an error |
| message that can be retrieved with `lt_dlerror'. |
| |
| -- Function: int lt_dladvise_destroy (lt_dladvise *ADVISE) |
| Recycle the memory used by ADVISE. For an example, see the |
| documentation for `lt_dladvise_ext'. |
| |
| On failure, `lt_dladvise_destroy' returns non-zero and sets an |
| error message that can be retrieved with `lt_dlerror'. |
| |
| -- Function: int lt_dladvise_ext (lt_dladvise *ADVISE) |
| Set the `ext' hint on ADVISE. Passing an ADVISE parameter to |
| `lt_dlopenadvise' with this hint set causes it to try to append |
| different file name extensions like `lt_dlopenext'. |
| |
| The following example is equivalent to calling `lt_dlopenext |
| (filename)': |
| |
| lt_dlhandle |
| my_dlopenext (const char *filename) |
| { |
| lt_dlhandle handle = 0; |
| lt_dladvise advise; |
| |
| if (!lt_dladvise_init (&advise) && !lt_dladvise_ext (&advise)) |
| handle = lt_dlopenadvise (filename, advise); |
| |
| lt_dladvise_destroy (&advise); |
| |
| return handle; |
| } |
| |
| On failure, `lt_dladvise_ext' returns non-zero and sets an error |
| message that can be retrieved with `lt_dlerror'. |
| |
| -- Function: int lt_dladvise_global (lt_dladvise *ADVISE) |
| Set the `symglobal' hint on ADVISE. Passing an ADVISE parameter |
| to `lt_dlopenadvise' with this hint set causes it to try to make |
| the loaded module's symbols globally available for resolving |
| unresolved symbols in subsequently loaded modules. |
| |
| If neither the `symglobal' nor the `symlocal' hints are set, or if |
| a module is loaded without using the `lt_dlopenadvise' call in any |
| case, then the visibility of the module's symbols will be as per |
| the default for the underlying module loader and OS. Even if a |
| suitable hint is passed, not all loaders are able to act upon it in |
| which case `lt_dlgetinfo' will reveal whether the hint was actually |
| followed. |
| |
| On failure, `lt_dladvise_global' returns non-zero and sets an error |
| message that can be retrieved with `lt_dlerror'. |
| |
| -- Function: int lt_dladvise_local (lt_dladvise *ADVISE) |
| Set the `symlocal' hint on ADVISE. Passing an ADVISE parameter to |
| `lt_dlopenadvise' with this hint set causes it to try to keep the |
| loaded module's symbols hidden so that they are not visible to |
| subsequently loaded modules. |
| |
| If neither the `symglobal' nor the `symlocal' hints are set, or if |
| a module is loaded without using the `lt_dlopenadvise' call in any |
| case, then the visibility of the module's symbols will be as per |
| the default for the underlying module loader and OS. Even if a |
| suitable hint is passed, not all loaders are able to act upon it in |
| which case `lt_dlgetinfo' will reveal whether the hint was actually |
| followed. |
| |
| On failure, `lt_dladvise_local' returns non-zero and sets an error |
| message that can be retrieved with `lt_dlerror'. |
| |
| -- Function: int lt_dladvise_resident (lt_dladvise *ADVISE) |
| Set the `resident' hint on ADVISE. Passing an ADVISE parameter to |
| `lt_dlopenadvise' with this hint set causes it to try to make the |
| loaded module resident in memory, so that it cannot be unloaded |
| with a later call to `lt_dlclose'. |
| |
| On failure, `lt_dladvise_resident' returns non-zero and sets an |
| error message that can be retrieved with `lt_dlerror'. |
| |
| -- Function: int lt_dladvise_preload (lt_dladvise *ADVISE) |
| Set the `preload' hint on ADVISE. Passing an ADVISE parameter to |
| `lt_dlopenadvise' with this hint set causes it to load only |
| preloaded modules, so that if a suitable preloaded module is not |
| found, `lt_dlopenadvise' will return `NULL'. |
| |
| -- Function: int lt_dlclose (lt_dlhandle HANDLE) |
| Decrement the reference count on the module HANDLE. If it drops |
| to zero and no other module depends on this module, then the |
| module is unloaded. Return 0 on success. |
| |
| -- Function: void * lt_dlsym (lt_dlhandle HANDLE, const char *NAME) |
| Return the address in the module HANDLE, where the symbol given by |
| the null-terminated string NAME is loaded. If the symbol cannot |
| be found, `NULL' is returned. |
| |
| -- Function: const char * lt_dlerror (void) |
| Return a human readable string describing the most recent error |
| that occurred from any of libltdl's functions. Return `NULL' if |
| no errors have occurred since initialization or since it was last |
| called. |
| |
| -- Function: int lt_dladdsearchdir (const char *SEARCH_DIR) |
| Append the search directory SEARCH_DIR to the current user-defined |
| library search path. Return 0 on success. |
| |
| -- Function: int lt_dlinsertsearchdir (const char *BEFORE, |
| const char *SEARCH_DIR) |
| Insert the search directory SEARCH_DIR into the user-defined |
| library search path, immediately before the element starting at |
| address BEFORE. If BEFORE is `NULL', then SEARCH_DIR is appending |
| as if `lt_dladdsearchdir' had been called. Return 0 on success. |
| |
| -- Function: int lt_dlsetsearchpath (const char *SEARCH_PATH) |
| Replace the current user-defined library search path with |
| SEARCH_PATH, which must be a list of absolute directories separated |
| by `LT_PATHSEP_CHAR'. Return 0 on success. |
| |
| -- Function: const char * lt_dlgetsearchpath (void) |
| Return the current user-defined library search path. |
| |
| -- Function: int lt_dlforeachfile (const char *SEARCH_PATH, |
| int (*FUNC) (const char *FILENAME, void * DATA), void * DATA) |
| In some applications you may not want to load individual modules |
| with known names, but rather find all of the modules in a set of |
| directories and load them all during initialisation. With this |
| function you can have libltdl scan the `LT_PATHSEP_CHAR'-delimited |
| directory list in SEARCH_PATH for candidates, and pass them, along |
| with DATA to your own callback function, FUNC. If SEARCH_PATH is |
| `NULL', then search all of the standard locations that `lt_dlopen' |
| would examine. This function will continue to make calls to FUNC |
| for each file that it discovers in SEARCH_PATH until one of these |
| calls returns non-zero, or until the files are exhausted. |
| `lt_dlforeachfile' returns the value returned by the last call |
| made to FUNC. |
| |
| For example you could define FUNC to build an ordered "argv"-like |
| vector of files using DATA to hold the address of the start of the |
| vector. |
| |
| -- Function: int lt_dlmakeresident (lt_dlhandle HANDLE) |
| Mark a module so that it cannot be `lt_dlclose'd. This can be |
| useful if a module implements some core functionality in your |
| project that would cause your code to crash if removed. Return 0 |
| on success. |
| |
| If you use `lt_dlopen (NULL)' to get a HANDLE for the running |
| binary, that handle will always be marked as resident, and |
| consequently cannot be successfully `lt_dlclose'd. |
| |
| -- Function: int lt_dlisresident (lt_dlhandle HANDLE) |
| Check whether a particular module has been marked as resident, |
| returning 1 if it has or 0 otherwise. If there is an error while |
| executing this function, return -1 and set an error message for |
| retrieval with `lt_dlerror'. |
| |
| ---------- Footnotes ---------- |
| |
| (1) Some platforms, notably Mac OS X, differentiate between a |
| runtime library that cannot be opened by `lt_dlopen' and a dynamic |
| module that can. For maximum portability you should try to ensure that |
| you only pass `lt_dlopen' objects that have been compiled with libtool's |
| `-module' flag. |
| |
| |
| File: libtool.info, Node: Modules for libltdl, Next: Thread Safety in libltdl, Prev: Libltdl interface, Up: Using libltdl |
| |
| 11.2 Creating modules that can be `dlopen'ed |
| ============================================ |
| |
| Libtool modules are created like normal libtool libraries with a few |
| exceptions: |
| |
| You have to link the module with libtool's `-module' switch, and you |
| should link any program that is intended to dlopen the module with |
| `-dlopen MODULENAME.LA' where possible, so that libtool can dlpreopen |
| the module on platforms that do not support dlopening. If the module |
| depends on any other libraries, make sure you specify them either when |
| you link the module or when you link programs that dlopen it. If you |
| want to disable versioning (*note Versioning::) for a specific module |
| you should link it with the `-avoid-version' switch. Note that libtool |
| modules don't need to have a "lib" prefix. However, Automake 1.4 or |
| higher is required to build such modules. |
| |
| Usually a set of modules provide the same interface, i.e. exports |
| the same symbols, so that a program can dlopen them without having to |
| know more about their internals: In order to avoid symbol conflicts all |
| exported symbols must be prefixed with "modulename_LTX_" (MODULENAME is |
| the name of the module). Internal symbols must be named in such a way |
| that they won't conflict with other modules, for example, by prefixing |
| them with "_modulename_". Although some platforms support having the |
| same symbols defined more than once it is generally not portable and it |
| makes it impossible to dlpreopen such modules. |
| |
| libltdl will automatically cut the prefix off to get the real name of |
| the symbol. Additionally, it supports modules that do not use a prefix |
| so that you can also dlopen non-libtool modules. |
| |
| `foo1.c' gives an example of a portable libtool module. Exported |
| symbols are prefixed with "foo1_LTX_", internal symbols with "_foo1_". |
| Aliases are defined at the beginning so that the code is more readable. |
| |
| /* aliases for the exported symbols */ |
| #define foo foo1_LTX_foo |
| #define bar foo1_LTX_bar |
| |
| /* a global variable definition */ |
| int bar = 1; |
| |
| /* a private function */ |
| int _foo1_helper() { |
| return bar; |
| } |
| |
| /* an exported function */ |
| int foo() { |
| return _foo1_helper(); |
| } |
| |
| The `Makefile.am' contains the necessary rules to build the module |
| `foo1.la': |
| |
| ... |
| lib_LTLIBRARIES = foo1.la |
| |
| foo1_la_SOURCES = foo1.c |
| foo1_la_LDFLAGS = -module |
| ... |
| |
| |
| File: libtool.info, Node: Thread Safety in libltdl, Next: User defined module data, Prev: Modules for libltdl, Up: Using libltdl |
| |
| 11.3 Using libltdl in a multi threaded environment |
| ================================================== |
| |
| Libltdl provides a wrapper around whatever dynamic run-time object |
| loading mechanisms are provided by the host system, many of which are |
| themselves not thread safe. Consequently libltdl cannot itself be |
| consistently thread safe. |
| |
| If you wish to use libltdl in a multithreaded environment, then you |
| must mutex lock around libltdl calls, since they may in turn be calling |
| non-thread-safe system calls on some target hosts. |
| |
| Some old releases of libtool provided a mutex locking API that was |
| unusable with POSIX threads, so callers were forced to lock around all |
| libltdl API calls anyway. That mutex locking API was next to useless, |
| and is not present in current releases. |
| |
| Some future release of libtool may provide a new POSIX thread |
| compliant mutex locking API. |
| |
| |
| File: libtool.info, Node: User defined module data, Next: Module loaders for libltdl, Prev: Thread Safety in libltdl, Up: Using libltdl |
| |
| 11.4 Data associated with loaded modules |
| ======================================== |
| |
| Some of the internal information about each loaded module that is |
| maintained by libltdl is available to the user, in the form of this |
| structure: |
| |
| -- Type: struct lt_dlinfo { char *FILENAME; char *NAME; int REF_COUNT; |
| int IS_RESIDENT; int IS_SYMGLOBAL; int IS_SYMLOCAL;} |
| `lt_dlinfo' is used to store information about a module. The |
| FILENAME attribute is a null-terminated character string of the |
| real module file name. If the module is a libtool module then |
| NAME is its module name (e.g. `"libfoo"' for `"dir/libfoo.la"'), |
| otherwise it is set to `NULL'. The REF_COUNT attribute is a |
| reference counter that describes how often the same module is |
| currently loaded. The remaining fields can be compared to any |
| hints that were passed to `lt_dlopenadvise' to determine whether |
| the underlying loader was able to follow them. |
| |
| The following function will return a pointer to libltdl's internal |
| copy of this structure for the given HANDLE: |
| |
| -- Function: const lt_dlinfo * lt_dlgetinfo (lt_dlhandle HANDLE) |
| Return a pointer to a struct that contains some information about |
| the module HANDLE. The contents of the struct must not be |
| modified. Return `NULL' on failure. |
| |
| Furthermore, in order to save you from having to keep a list of the |
| handles of all the modules you have loaded, these functions allow you to |
| iterate over libltdl's list of loaded modules: |
| |
| -- Type: lt_dlinterface_id |
| The opaque type used to hold the module interface details for each |
| registered libltdl client. |
| |
| -- Type: int lt_dlhandle_interface (lt_dlhandle HANDLE, |
| const char *ID_STRING) |
| Functions of this type are called to check that a handle conforms |
| to a library's expected module interface when iterating over the |
| global handle list. You should be careful to write a callback |
| function of this type that can correctly identify modules that |
| belong to this client, both to prevent other clients from |
| accidentally finding your loaded modules with the iterator |
| functions below, and vice versa. The best way to do this is to |
| check that module HANDLE conforms to the interface specification |
| of your loader using `lt_dlsym'. |
| |
| The callback may be given *every* module loaded by all the libltdl |
| module clients in the current address space, including any modules |
| loaded by other libraries such as libltdl itself, and should |
| return non-zero if that module does not fulfill the interface |
| requirements of your loader. |
| |
| int |
| my_interface_cb (lt_dlhandle handle, const char *id_string) |
| { |
| char *(*module_id) (void) = NULL; |
| |
| /* A valid my_module must provide all of these symbols. */ |
| if (!((module_id = (char*(*)(void)) lt_dlsym ("module_version")) |
| && lt_dlsym ("my_module_entrypoint"))) |
| return 1; |
| |
| if (strcmp (id_string, module_id()) != 0) |
| return 1; |
| |
| return 0; |
| } |
| |
| -- Function: lt_dlinterface_id lt_dlinterface_register |
| (const char *ID_STRING, lt_dlhandle_interface *IFACE) |
| Use this function to register your interface validator with |
| libltdl, and in return obtain a unique key to store and retrieve |
| per-module data. You supply an ID_STRING and IFACE so that the |
| resulting `lt_dlinterface_id' can be used to filter the module |
| handles returned by the iteration functions below. If IFACE is |
| `NULL', all modules will be matched. |
| |
| -- Function: void lt_dlinterface_free (lt_dlinterface_id IFACE) |
| Release the data associated with IFACE. |
| |
| -- Function: int lt_dlhandle_map (lt_dlinterface_id IFACE, |
| int (*FUNC) (lt_dlhandle HANDLE, void * DATA), void * DATA) |
| For each module that matches IFACE, call the function FUNC. When |
| writing the FUNC callback function, the argument HANDLE is the |
| handle of a loaded module, and DATA is the last argument passed to |
| `lt_dlhandle_map'. As soon as FUNC returns a non-zero value for |
| one of the handles, `lt_dlhandle_map' will stop calling FUNC and |
| immediately return that non-zero value. Otherwise 0 is eventually |
| returned when FUNC has been successfully called for all matching |
| modules. |
| |
| -- Function: lt_dlhandle lt_dlhandle_iterate |
| (lt_dlinterface_id IFACE, lt_dlhandle PLACE) |
| Iterate over the module handles loaded by IFACE, returning the |
| first matching handle in the list if PLACE is `NULL', and the next |
| one on subsequent calls. If PLACE is the last element in the list |
| of eligible modules, this function returns `NULL'. |
| |
| lt_dlhandle handle = 0; |
| lt_dlinterface_id iface = my_interface_id; |
| |
| while ((handle = lt_dlhandle_iterate (iface, handle))) |
| { |
| ... |
| } |
| |
| -- Function: lt_dlhandle lt_dlhandle_fetch (lt_dlinterface_id IFACE, |
| const char *MODULE_NAME) |
| Search through the module handles loaded by IFACE for a module |
| named MODULE_NAME, returning its handle if found or else `NULL' if |
| no such named module has been loaded by IFACE. |
| |
| However, you might still need to maintain your own list of loaded |
| module handles (in parallel with the list maintained inside libltdl) if |
| there were any other data that your application wanted to associate |
| with each open module. Instead, you can use the following API calls to |
| do that for you. You must first obtain a unique interface id from |
| libltdl as described above, and subsequently always use it to retrieve |
| the data you stored earlier. This allows different libraries to each |
| store their own data against loaded modules, without interfering with |
| one another. |
| |
| -- Function: void * lt_dlcaller_set_data (lt_dlinterface_id KEY, |
| lt_dlhandle HANDLE, void * DATA) |
| Set DATA as the set of data uniquely associated with KEY and |
| HANDLE for later retrieval. This function returns the DATA |
| previously associated with KEY and HANDLE if any. A result of 0, |
| may indicate that a diagnostic for the last error (if any) is |
| available from `lt_dlerror()'. |
| |
| For example, to correctly remove some associated data: |
| |
| void *stale = lt_dlcaller_set_data (key, handle, 0); |
| if (stale != NULL) |
| { |
| free (stale); |
| } |
| else |
| { |
| char *error_msg = lt_dlerror (); |
| |
| if (error_msg != NULL) |
| { |
| my_error_handler (error_msg); |
| return STATUS_FAILED; |
| } |
| } |
| |
| -- Function: void * lt_dlcaller_get_data (lt_dlinterface_id KEY, |
| lt_dlhandle HANDLE) |
| Return the address of the data associated with KEY and HANDLE, or |
| else `NULL' if there is none. |
| |
| Old versions of libltdl also provided a simpler, but similar, API |
| based around `lt_dlcaller_id'. Unfortunately, it had no provision for |
| detecting whether a module belonged to a particular interface as |
| libltdl didn't support multiple loaders in the same address space at |
| that time. Those APIs are no longer supported as there would be no way |
| to stop clients of the old APIs from seeing (and accidentally altering) |
| modules loaded by other libraries. |
| |
| |
| File: libtool.info, Node: Module loaders for libltdl, Next: Distributing libltdl, Prev: User defined module data, Up: Using libltdl |
| |
| 11.5 How to create and register new module loaders |
| ================================================== |
| |
| Sometimes libltdl's many ways of gaining access to modules are not |
| sufficient for the purposes of a project. You can write your own |
| loader, and register it with libltdl so that `lt_dlopen' will be able |
| to use it. |
| |
| Writing a loader involves writing at least three functions that can |
| be called by `lt_dlopen', `lt_dlsym' and `lt_dlclose'. Optionally, you |
| can provide a finalisation function to perform any cleanup operations |
| when `lt_dlexit' executes, and a symbol prefix string that will be |
| prepended to any symbols passed to `lt_dlsym'. These functions must |
| match the function pointer types below, after which they can be |
| allocated to an instance of `lt_user_dlloader' and registered. |
| |
| Registering the loader requires that you choose a name for it, so |
| that it can be recognised by `lt_dlloader_find' and removed with |
| `lt_dlloader_remove'. The name you choose must be unique, and not |
| already in use by libltdl's builtin loaders: |
| |
| "dlopen" |
| The system dynamic library loader, if one exists. |
| |
| "dld" |
| The GNU dld loader, if `libdld' was installed when libltdl was |
| built. |
| |
| "dlpreload" |
| The loader for `lt_dlopen'ing of preloaded static modules. |
| |
| The prefix "dl" is reserved for loaders supplied with future |
| versions of libltdl, so you should not use that for your own loader |
| names. |
| |
| The following types are defined in `ltdl.h': |
| |
| -- Type: lt_module |
| `lt_module' is a dlloader dependent module. The dynamic module |
| loader extensions communicate using these low level types. |
| |
| -- Type: lt_dlloader |
| `lt_dlloader' is a handle for module loader types. |
| |
| -- Type: lt_user_data |
| `lt_user_data' is used for specifying loader instance data. |
| |
| -- Type: struct lt_user_dlloader {const char *SYM_PREFIX; |
| lt_module_open *MODULE_OPEN; lt_module_close *MODULE_CLOSE; |
| lt_find_sym *FIND_SYM; lt_dlloader_exit *DLLOADER_EXIT; } |
| If you want to define a new way to open dynamic modules, and have |
| the `lt_dlopen' API use it, you need to instantiate one of these |
| structures and pass it to `lt_dlloader_add'. You can pass whatever |
| you like in the DLLOADER_DATA field, and it will be passed back as |
| the value of the first parameter to each of the functions |
| specified in the function pointer fields. |
| |
| -- Type: lt_module lt_module_open (const char *FILENAME) |
| The type of the loader function for an `lt_dlloader' module |
| loader. The value set in the dlloader_data field of the `struct |
| lt_user_dlloader' structure will be passed into this function in |
| the LOADER_DATA parameter. Implementation of such a function |
| should attempt to load the named module, and return an `lt_module' |
| suitable for passing in to the associated `lt_module_close' and |
| `lt_sym_find' function pointers. If the function fails it should |
| return `NULL', and set the error message with `lt_dlseterror'. |
| |
| -- Type: int lt_module_close (lt_user_data LOADER_DATA, |
| lt_module MODULE) |
| The type of the unloader function for a user defined module loader. |
| Implementation of such a function should attempt to release any |
| resources tied up by the MODULE module, and then unload it from |
| memory. If the function fails for some reason, set the error |
| message with `lt_dlseterror' and return non-zero. |
| |
| -- Type: void * lt_find_sym (lt_module MODULE, const char *SYMBOL) |
| The type of the symbol lookup function for a user defined module |
| loader. Implementation of such a function should return the |
| address of the named SYMBOL in the module MODULE, or else set the |
| error message with `lt_dlseterror' and return `NULL' if lookup |
| fails. |
| |
| -- Type: int lt_dlloader_exit (lt_user_data LOADER_DATA) |
| The type of the finalisation function for a user defined module |
| loader. Implementation of such a function should free any |
| resources associated with the loader, including any user specified |
| data in the `dlloader_data' field of the `lt_user_dlloader'. If |
| non-`NULL', the function will be called by `lt_dlexit', and |
| `lt_dlloader_remove'. |
| |
| For example: |
| |
| int |
| register_myloader (void) |
| { |
| lt_user_dlloader dlloader; |
| |
| /* User modules are responsible for their own initialisation. */ |
| if (myloader_init () != 0) |
| return MYLOADER_INIT_ERROR; |
| |
| dlloader.sym_prefix = NULL; |
| dlloader.module_open = myloader_open; |
| dlloader.module_close = myloader_close; |
| dlloader.find_sym = myloader_find_sym; |
| dlloader.dlloader_exit = myloader_exit; |
| dlloader.dlloader_data = (lt_user_data)myloader_function; |
| |
| /* Add my loader as the default module loader. */ |
| if (lt_dlloader_add (lt_dlloader_next (NULL), &dlloader, |
| "myloader") != 0) |
| return ERROR; |
| |
| return OK; |
| } |
| |
| Note that if there is any initialisation required for the loader, it |
| must be performed manually before the loader is registered - libltdl |
| doesn't handle user loader initialisation. |
| |
| Finalisation _is_ handled by libltdl however, and it is important to |
| ensure the `dlloader_exit' callback releases any resources claimed |
| during the initialisation phase. |
| |
| libltdl provides the following functions for writing your own module |
| loaders: |
| |
| -- Function: int lt_dlloader_add (lt_dlloader *PLACE, |
| lt_user_dlloader *DLLOADER, const char *LOADER_NAME) |
| Add a new module loader to the list of all loaders, either as the |
| last loader (if PLACE is `NULL'), else immediately before the |
| loader passed as PLACE. LOADER_NAME will be returned by |
| `lt_dlloader_name' if it is subsequently passed a newly registered |
| loader. These LOADER_NAMEs must be unique, or |
| `lt_dlloader_remove' and `lt_dlloader_find' cannot work. Returns |
| 0 for success. |
| |
| /* Make myloader be the last one. */ |
| if (lt_dlloader_add (NULL, myloader) != 0) |
| perror (lt_dlerror ()); |
| |
| -- Function: int lt_dlloader_remove (const char *LOADER_NAME) |
| Remove the loader identified by the unique name, LOADER_NAME. |
| Before this can succeed, all modules opened by the named loader |
| must have been closed. Returns 0 for success, otherwise an error |
| message can be obtained from `lt_dlerror'. |
| |
| /* Remove myloader. */ |
| if (lt_dlloader_remove ("myloader") != 0) |
| perror (lt_dlerror ()); |
| |
| -- Function: lt_dlloader * lt_dlloader_next (lt_dlloader *PLACE) |
| Iterate over the module loaders, returning the first loader if |
| PLACE is `NULL', and the next one on subsequent calls. The handle |
| is for use with `lt_dlloader_add'. |
| |
| /* Make myloader be the first one. */ |
| if (lt_dlloader_add (lt_dlloader_next (NULL), myloader) != 0) |
| return ERROR; |
| |
| -- Function: lt_dlloader * lt_dlloader_find (const char *LOADER_NAME) |
| Return the first loader with a matching LOADER_NAME identifier, or |
| else `NULL', if the identifier is not found. |
| |
| The identifiers that may be used by libltdl itself, if the host |
| architecture supports them are "dlopen"(1), "dld" and "dlpreload". |
| |
| /* Add a user loader as the next module loader to be tried if |
| the standard dlopen loader were to fail when lt_dlopening. */ |
| if (lt_dlloader_add (lt_dlloader_find ("dlopen"), myloader) != 0) |
| return ERROR; |
| |
| -- Function: const char * lt_dlloader_name (lt_dlloader *PLACE) |
| Return the identifying name of PLACE, as obtained from |
| `lt_dlloader_next' or `lt_dlloader_find'. If this function fails, |
| it will return `NULL' and set an error for retrieval with |
| `lt_dlerror'. |
| |
| -- Function: lt_user_data * lt_dlloader_data (lt_dlloader *PLACE) |
| Return the address of the `dlloader_data' of PLACE, as obtained |
| from `lt_dlloader_next' or `lt_dlloader_find'. If this function |
| fails, it will return `NULL' and set an error for retrieval with |
| `lt_dlerror'. |
| |
| 11.5.1 Error handling within user module loaders |
| ------------------------------------------------ |
| |
| -- Function: int lt_dladderror (const char *DIAGNOSTIC) |
| This function allows you to integrate your own error messages into |
| `lt_dlerror'. Pass in a suitable diagnostic message for return by |
| `lt_dlerror', and an error identifier for use with `lt_dlseterror' |
| is returned. |
| |
| If the allocation of an identifier fails, this function returns -1. |
| |
| int myerror = lt_dladderror ("Doh!"); |
| if (myerror < 0) |
| perror (lt_dlerror ()); |
| |
| -- Function: int lt_dlseterror (int ERRORCODE) |
| When writing your own module loaders, you should use this function |
| to raise errors so that they are propagated through the |
| `lt_dlerror' interface. All of the standard errors used by |
| libltdl are declared in `ltdl.h', or you can add more of your own |
| with `lt_dladderror'. This function returns 0 on success. |
| |
| if (lt_dlseterror (LTDL_ERROR_NO_MEMORY) != 0) |
| perror (lt_dlerror ()); |
| |
| ---------- Footnotes ---------- |
| |
| (1) This is used for the host dependent module loading API - |
| `shl_load' and `LoadLibrary' for example |
| |
| |
| File: libtool.info, Node: Distributing libltdl, Prev: Module loaders for libltdl, Up: Using libltdl |
| |
| 11.6 How to distribute libltdl with your package |
| ================================================ |
| |
| Even though libltdl is installed together with libtool, you may wish to |
| include libltdl in the distribution of your package, for the |
| convenience of users of your package that don't have libtool or libltdl |
| installed, or if you are using features of a very new version of |
| libltdl that you don't expect your users to have yet. In such cases, |
| you must decide which flavor of libltdl you want to use: a convenience |
| library or an installable libtool library. |
| |
| The most simplistic way to add `libltdl' to your package is to copy |
| all the `libltdl' source files to a subdirectory within your package |
| and to build and link them along with the rest of your sources. To |
| help you do this, the m4 macros for Autoconf are available in |
| `ltdl.m4'. You must ensure that they are available in `aclocal.m4' |
| before you run Autoconf(1). Having made the macros available, you must |
| add a call to the `LTDL_INIT' macro (after the call to `LT_INIT') to |
| your package's `configure.ac' to perform the configure time checks |
| required to build the library correctly. Unfortunately, this method |
| has problems if you then try to link the package binaries with an |
| installed libltdl, or a library that depends on libltdl, because of the |
| duplicate symbol definitions. For example, ultimately linking against |
| two different versions of libltdl, or against both a local convenience |
| library and an installed libltdl is bad. Ensuring that only one copy |
| of the libltdl sources are linked into any program is left as an |
| exercise for the reader. |
| |
| -- Macro: LT_CONFIG_LTDL_DIR (DIRECTORY) |
| Declare DIRECTORY to be the location of the `libltdl' source |
| files, for `libtoolize --ltdl' to place them. *Note Invoking |
| libtoolize::, for more details. Provided that you add an |
| appropriate `LT_CONFIG_LTDL_DIR' call in your `configure.ac' |
| before calling `libtoolize', the appropriate `libltdl' files will |
| be installed automatically. |
| |
| -- Macro: LTDL_INIT (OPTIONS) |
| -- Macro: LT_WITH_LTDL |
| -- Macro: AC_WITH_LTDL |
| `AC_WITH_LTDL' and `LT_WITH_LTDL' are deprecated names for older |
| versions of this macro; `autoupdate' will update your |
| `configure.ac' file. |
| |
| This macro adds the following options to the `configure' script: |
| |
| `--with-ltdl-include INSTALLED-LTDL-HEADER-DIR' |
| The `LTDL_INIT' macro will look in the standard header file |
| locations to find the installed `libltdl' headers. If |
| `LTDL_INIT' can't find them by itself, the person who builds |
| your package can use this option to tell `configure' where |
| the installed `libltdl' headers are. |
| |
| `--with-ltdl-lib INSTALLED-LTDL-LIBRARY-DIR' |
| Similarly, the person building your package can use this |
| option to help `configure' find the installed `libltdl.la'. |
| |
| `--with-included-ltdl' |
| If there is no installed `libltdl', or in any case if the |
| person building your package would rather use the `libltdl' |
| sources shipped with the package in the subdirectory named by |
| `LT_CONFIG_LTDL_DIR', they should pass this option to |
| `configure'. |
| |
| If the `--with-included-ltdl' is not passed at configure time, and |
| an installed `libltdl' is not found(2), then `configure' will exit |
| immediately with an error that asks the user to either specify the |
| location of an installed `libltdl' using the `--with-ltdl-include' |
| and `--with-ltdl-lib' options, or to build with the `libltdl' |
| sources shipped with the package by passing `--with-included-ltdl'. |
| |
| If an installed `libltdl' is found, then `LIBLTDL' is set to the |
| link flags needed to use it, and `LTDLINCL' to the preprocessor |
| flags needed to find the installed headers, and `LTDLDEPS' will be |
| empty. Note, however, that no version checking is performed. You |
| should manually check for the `libltdl' features you need in |
| `configure.ac': |
| |
| LT_INIT([dlopen]) |
| LTDL_INIT |
| |
| # The lt_dladvise_init symbol was added with libtool-2.2 |
| if test "x$with_included_ltdl" != "xyes"; then |
| save_CFLAGS="$CFLAGS" |
| save_LDFLAGS="$LDFLAGS" |
| CFLAGS="$CFLAGS $LTDLINCL" |
| LDFLAGS="$LDFLAGS $LIBLTDL" |
| AC_CHECK_LIB([ltdl], [lt_dladvise_init], |
| [], |
| [AC_MSG_ERROR([installed libltdl is too old])]) |
| LDFLAGS="$save_LDFLAGS" |
| CFLAGS="$save_CFLAGS" |
| fi |
| |
| OPTIONS may include no more than one of the following build modes |
| depending on how you want your project to build `libltdl': |
| `nonrecursive', `recursive', or `subproject'. In order for |
| `libtoolize' to detect this option correctly, if you supply one of |
| these arguments, they must be given literally (i.e., macros or |
| shell variables that expand to the correct ltdl mode will not |
| work). |
| |
| `nonrecursive' |
| This is how the Libtool project distribution builds the |
| `libltdl' we ship and install. If you wish to use Automake |
| to build `libltdl' without invoking a recursive make to |
| descend into the `libltdl' subdirectory, then use this |
| option. You will need to set your configuration up carefully |
| to make this work properly, and you will need releases of |
| Autoconf and Automake that support `subdir-objects' and |
| `LIBOBJDIR' properly. In your `configure.ac', add: |
| |
| AM_INIT_AUTOMAKE([subdir-objects]) |
| AC_CONFIG_HEADERS([config.h]) |
| LT_CONFIG_LTDL_DIR([libltdl]) |
| LT_INIT([dlopen]) |
| LTDL_INIT([nonrecursive]) |
| |
| You _have to_ use a config header, but it may have a name |
| different than `config.h'. |
| |
| Also, add the following near the top of your `Makefile.am': |
| |
| AM_CPPFLAGS = |
| AM_LDFLAGS = |
| |
| BUILT_SOURCES = |
| EXTRA_DIST = |
| CLEANFILES = |
| MOSTLYCLEANFILES = |
| |
| include_HEADERS = |
| noinst_LTLIBRARIES = |
| lib_LTLIBRARIES = |
| EXTRA_LTLIBRARIES = |
| |
| include libltdl/Makefile.inc |
| |
| Unless you build no other libraries from this `Makefile.am', |
| you will also need to change `lib_LTLIBRARIES' to assign with |
| `+=' so that the `libltdl' targets declared in `Makefile.inc' |
| are not overwritten. |
| |
| `recursive' |
| This build mode still requires that you use Automake, but (in |
| contrast with `nonrecursive') uses the more usual device of |
| starting another `make' process in the `libltdl' |
| subdirectory. To use this mode, you should add to your |
| `configure.ac': |
| |
| AM_INIT_AUTOMAKE |
| AC_CONFIG_HEADERS([config.h]) |
| LT_CONFIG_LTDL_DIR([libltdl]) |
| LT_INIT([dlopen]) |
| LTDL_INIT([recursive]) |
| AC_CONFIG_FILES([libltdl/Makefile]) |
| |
| Again, you _have to_ use a config header, but it may have a |
| name different than `config.h' if you like. |
| |
| Also, add this to your `Makefile.am': |
| |
| SUBDIRS = libltdl |
| |
| `subproject' |
| This mode is the default unless you explicitly add |
| `recursive' or `nonrecursive' to your `LTDL_INIT' options; |
| `subproject' is the only mode supported by previous releases |
| of libltdl. Even if you do not use Autoconf in the parent |
| project, then, in `subproject' mode, still `libltdl' contains |
| all the necessary files to configure and build itself - you |
| just need to arrange for your build system to call |
| `libltdl/configure' with appropriate options, and then run |
| `make' in the `libltdl' subdirectory. |
| |
| If you _are_ using Autoconf and Automake, then you will need |
| to add the following to your `configure.ac': |
| |
| LT_CONFIG_LTDL_DIR([libltdl]) |
| LTDL_INIT |
| |
| and to `Makefile.am': |
| |
| SUBDIRS = libltdl |
| |
| Aside from setting the libltdl build mode, there are other keywords |
| that you can pass to `LTDL_INIT' to modify its behavior when |
| `--with-included-ltdl' has been given: |
| |
| `convenience' |
| This is the default unless you explicitly add `installable' to |
| your `LTDL_INIT' options. |
| |
| This keyword will cause options to be passed to the |
| `configure' script in the subdirectory named by |
| `LT_CONFIG_LTDL_DIR' in order to cause it to be built as a |
| convenience library. If you're not using automake, you will |
| need to define `top_build_prefix', `top_builddir', and |
| `top_srcdir' in your makefile so that `LIBLTDL', `LTDLDEPS', |
| and `LTDLINCL' expand correctly. |
| |
| One advantage of the convenience library is that it is not |
| installed, so the fact that you use `libltdl' will not be |
| apparent to the user, and it won't overwrite a pre-installed |
| version of `libltdl' the system might already have in the |
| installation directory. On the other hand, if you want to |
| upgrade `libltdl' for any reason (e.g. a bugfix) you'll have |
| to recompile your package instead of just replacing the |
| shared installed version of `libltdl'. However, if your |
| programs or libraries are linked with other libraries that |
| use such a pre-installed version of `libltdl', you may get |
| linker errors or run-time crashes. Another problem is that |
| you cannot link the convenience library into more than one |
| libtool library, then link a single program with those |
| libraries, because you may get duplicate symbols. In general |
| you can safely use the convenience library in programs that |
| don't depend on other libraries that might use `libltdl' too. |
| |
| `installable' |
| This keyword will pass options to the `configure' script in |
| the subdirectory named by `LT_CONFIG_LTDL_DIR' in order to |
| cause it to be built as an installable library. If you're not |
| using automake, you will need to define `top_build_prefix', |
| `top_builddir' and `top_srcdir' in your makefile so that |
| `LIBLTDL', `LTDLDEPS', and `LTDLINCL' are expanded properly. |
| |
| Be aware that you could overwrite another `libltdl' already |
| installed to the same directory if you use this option. |
| |
| Whatever method you use, `LTDL_INIT' will define the shell variable |
| `LIBLTDL' to the link flag that you should use to link with `libltdl', |
| the shell variable `LTDLDEPS' to the files that can be used as a |
| dependency in `Makefile' rules, and the shell variable `LTDLINCL' to |
| the preprocessor flag that you should use to compile programs that |
| include `ltdl.h'. So, when you want to link a program with libltdl, be |
| it a convenience, installed or installable library, just use |
| `$(LTDLINCL)' for preprocessing and compilation, and `$(LIBLTDL)' for |
| linking. |
| |
| * If your package is built using an installed version of `libltdl', |
| `LIBLTDL' will be set to the compiler flags needed to link against |
| the installed library, `LTDLDEPS' will be empty, and `LTDLINCL' |
| will be set to the compiler flags needed to find the `libltdl' |
| header files. |
| |
| * If your package is built using the convenience libltdl, `LIBLTDL' |
| and `LTDLDEPS' will be the pathname for the convenience version of |
| libltdl (starting with `${top_builddir}/' or |
| `${top_build_prefix}') and `LTDLINCL' will be `-I' followed by the |
| directory that contains `ltdl.h' (starting with `${top_srcdir}/'). |
| |
| * If an installable version of the included `libltdl' is being |
| built, its pathname starting with `${top_builddir}/' or |
| `${top_build_prefix}', will be stored in `LIBLTDL' and `LTDLDEPS', |
| and `LTDLINCL' will be set just like in the case of convenience |
| library. |
| |
| You should probably also use the `dlopen' option to `LT_INIT' in |
| your `configure.ac', otherwise libtool will assume no dlopening |
| mechanism is supported, and revert to dlpreopening, which is probably |
| not what you want. Avoid using the `-static', `-static-libtool-libs', |
| or `-all-static' switches when linking programs with libltdl. This |
| will not work on all platforms, because the dlopening functions may not |
| be available for static linking. |
| |
| The following example shows you how to embed an installable libltdl |
| in your package. In order to use the convenience variant, just replace |
| the `LTDL_INIT' option `installable' with `convenience'. We assume |
| that libltdl was embedded using `libtoolize --ltdl'. |
| |
| configure.ac: |
| ... |
| # Name the subdirectory that contains libltdl sources |
| LT_CONFIG_LTDL_DIR([libltdl]) |
| |
| # Configure libtool with dlopen support if possible |
| LT_INIT([dlopen]) |
| |
| # Enable building of the installable libltdl library |
| LTDL_INIT([installable]) |
| ... |
| |
| Makefile.am: |
| ... |
| SUBDIRS = libltdl |
| |
| AM_CPPFLAGS = $(LTDLINCL) |
| |
| myprog_LDFLAGS = -export-dynamic |
| myprog_LDADD = $(LIBLTDL) -dlopen self -dlopen foo1.la |
| myprog_DEPENDENCIES = $(LTDLDEPS) foo1.la |
| ... |
| |
| -- Macro: LTDL_INSTALLABLE |
| -- Macro: AC_LIBLTDL_INSTALLABLE |
| These macros are deprecated, the `installable' option to |
| `LTDL_INIT' should be used instead. |
| |
| -- Macro: LTDL_CONVENIENCE |
| -- Macro: AC_LIBLTDL_CONVENIENCE |
| These macros are deprecated, the `convenience' option to |
| `LTDL_INIT' should be used instead. |
| |
| ---------- Footnotes ---------- |
| |
| (1) We used to recommend adding the contents of `ltdl.m4' to |
| `acinclude.m4', but with `aclocal' from a modern Automake (1.8 or |
| newer) and this release of libltdl that is not only unnecessary but |
| makes it easy to forget to upgrade `acinclude.m4' if you move to a |
| different release of libltdl. |
| |
| (2) Even if libltdl is installed, `LTDL_INIT' may fail to detect it |
| if libltdl depends on symbols provided by libraries other than the C |
| library. |
| |
| |
| File: libtool.info, Node: Trace interface, Next: FAQ, Prev: Using libltdl, Up: Top |
| |
| 12 Libtool's trace interface |
| **************************** |
| |
| This section describes macros whose sole purpose is to be traced using |
| Autoconf's `--trace' option (*note The Autoconf Manual: |
| (autoconf)autoconf Invocation.) to query the Libtool configuration of a |
| project. These macros are called by Libtool internals and should never |
| be called by user code; they should only be traced. |
| |
| -- Macro: LT_SUPPORTED_TAG (TAG) |
| This macro is called once for each language enabled in the |
| package. Its only argument, TAG, is the tag-name corresponding to |
| the language (*note Tags::). |
| |
| You can therefore retrieve the list of all tags enabled in a |
| project using the following command: |
| autoconf --trace 'LT_SUPPORTED_TAG:$1' |
| |
| |
| File: libtool.info, Node: FAQ, Next: Troubleshooting, Prev: Trace interface, Up: Top |
| |
| 13 Frequently Asked Questions about libtool |
| ******************************************* |
| |
| This chapter covers some questions that often come up on the mailing |
| lists. |
| |
| * Menu: |
| |
| * Stripped link flags:: Dropped flags when creating a library |
| |
| |
| File: libtool.info, Node: Stripped link flags, Up: FAQ |
| |
| 13.1 Why does libtool strip link flags when creating a library? |
| =============================================================== |
| |
| When creating a shared library, but not when compiling or creating a |
| program, `libtool' drops some flags from the command line provided by |
| the user. This is done because flags unknown to `libtool' may |
| interfere with library creation or require additional support from |
| `libtool', and because omitting flags is usually the conservative |
| choice for a successful build. |
| |
| If you encounter flags that you think are useful to pass, as a |
| work-around you can prepend flags with `-Wc,' or `-Xcompiler ' to allow |
| them to be passed through to the compiler driver (*note Link mode::). |
| Another possibility is to add flags already to the compiler command at |
| `configure' run time: |
| |
| ./configure CC='gcc -m64' |
| |
| If you think `libtool' should let some flag through by default, |
| here's how you can test such an inclusion: grab the Libtool development |
| tree, edit the `ltmain.m4sh' file in the `libltdl/config' subdirectory |
| to pass through the flag (search for `Flags to be passed through'), |
| re-bootstrap and build with the flags in question added to `LDFLAGS', |
| `CFLAGS', `CXXFLAGS', etc. on the `configure' command line as |
| appropriate. Run the testsuite as described in the `README' file and |
| report results to the Libtool bug reporting address |
| <bug-libtool@gnu.org>. |
| |
| |
| File: libtool.info, Node: Troubleshooting, Next: Maintaining, Prev: FAQ, Up: Top |
| |
| 14 Troubleshooting |
| ****************** |
| |
| Libtool is under constant development, changing to remain up-to-date |
| with modern operating systems. If libtool doesn't work the way you |
| think it should on your platform, you should read this chapter to help |
| determine what the problem is, and how to resolve it. |
| |
| * Menu: |
| |
| * Libtool test suite:: Libtool's self-tests. |
| * Reporting bugs:: How to report problems with libtool. |
| |
| |
| File: libtool.info, Node: Libtool test suite, Next: Reporting bugs, Up: Troubleshooting |
| |
| 14.1 The libtool test suite |
| =========================== |
| |
| Libtool comes with two integrated sets of tests to check that your build |
| is sane, that test its capabilities, and report obvious bugs in the |
| libtool program. These tests, too, are constantly evolving, based on |
| past problems with libtool, and known deficiencies in other operating |
| systems. |
| |
| As described in the `README' file, you may run `make -k check' after |
| you have built libtool (possibly before you install it) in order to |
| make sure that it meets basic functional requirements. |
| |
| * Menu: |
| |
| * Test descriptions:: The contents of the old test suite. |
| * When tests fail:: What to do when a test fails. |
| |
| |
| File: libtool.info, Node: Test descriptions, Next: When tests fail, Up: Libtool test suite |
| |
| 14.1.1 Description of test suite |
| -------------------------------- |
| |
| Here is a list of the current programs in the old test suite, and what |
| they test for: |
| |
| `cdemo-conf.test' |
| `cdemo-make.test' |
| `cdemo-exec.test' |
| `cdemo-static.test' |
| `cdemo-static-make.test' |
| `cdemo-static-exec.test' |
| `cdemo-shared.test' |
| `cdemo-shared-make.test' |
| `cdemo-shared-exec.test' |
| `cdemo-undef.test' |
| `cdemo-undef-make.test' |
| `cdemo-undef-exec.test' |
| These programs check to see that the `tests/cdemo' subdirectory of |
| the libtool distribution can be configured and built correctly. |
| |
| The `tests/cdemo' subdirectory contains a demonstration of libtool |
| convenience libraries, a mechanism that allows build-time static |
| libraries to be created, in a way that their components can be |
| later linked into programs or other libraries, even shared ones. |
| |
| The tests matching `cdemo-*make.test' and `cdemo-*exec.test' are |
| executed three times, under three different libtool configurations: |
| `cdemo-conf.test' configures `cdemo/libtool' to build both static |
| and shared libraries (the default for platforms that support |
| both), `cdemo-static.test' builds only static libraries |
| (`--disable-shared'), and `cdemo-shared.test' builds only shared |
| libraries (`--disable-static'). |
| |
| The test `cdemo-undef.test' tests the generation of shared |
| libraries with undefined symbols on systems that allow this. |
| |
| `demo-conf.test' |
| `demo-make.test' |
| `demo-exec.test' |
| `demo-inst.test' |
| `demo-unst.test' |
| `demo-static.test' |
| `demo-static-make.test' |
| `demo-static-exec.test' |
| `demo-static-inst.test' |
| `demo-static-unst.test' |
| `demo-shared.test' |
| `demo-shared-make.test' |
| `demo-shared-exec.test' |
| `demo-shared-inst.test' |
| `demo-shared-unst.test' |
| `demo-nofast.test' |
| `demo-nofast-make.test' |
| `demo-nofast-exec.test' |
| `demo-nofast-inst.test' |
| `demo-nofast-unst.test' |
| `demo-pic.test' |
| `demo-pic-make.test' |
| `demo-pic-exec.test' |
| `demo-nopic.test' |
| `demo-nopic-make.test' |
| `demo-nopic-exec.test' |
| These programs check to see that the `tests/demo' subdirectory of |
| the libtool distribution can be configured, built, installed, and |
| uninstalled correctly. |
| |
| The `tests/demo' subdirectory contains a demonstration of a trivial |
| package that uses libtool. The tests matching `demo-*make.test', |
| `demo-*exec.test', `demo-*inst.test' and `demo-*unst.test' are |
| executed four times, under four different libtool configurations: |
| `demo-conf.test' configures `demo/libtool' to build both static |
| and shared libraries, `demo-static.test' builds only static |
| libraries (`--disable-shared'), and `demo-shared.test' builds only |
| shared libraries (`--disable-static'). `demo-nofast.test' |
| configures `demo/libtool' to disable the fast-install mode |
| (`--enable-fast-install=no'). `demo-pic.test' configures |
| `demo/libtool' to prefer building PIC code (`--with-pic'), |
| `demo-nopic.test' to prefer non-PIC code (`--without-pic'). |
| |
| `demo-deplibs.test' |
| Many systems cannot link static libraries into shared libraries. |
| libtool uses a `deplibs_check_method' to prevent such cases. This |
| tests checks whether libtool's `deplibs_check_method' works |
| properly. |
| |
| `demo-hardcode.test' |
| On all systems with shared libraries, the location of the library |
| can be encoded in executables that are linked against it *note |
| Linking executables::. This test checks the conditions under |
| which your system linker hardcodes the library location, and |
| guarantees that they correspond to libtool's own notion of how |
| your linker behaves. |
| |
| `demo-relink.test' |
| `depdemo-relink.test' |
| These tests check whether variable `shlibpath_overrides_runpath' is |
| properly set. If the test fails, it will indicate what the |
| variable should have been set to. |
| |
| `demo-noinst-link.test' |
| Checks whether libtool will not try to link with a previously |
| installed version of a library when it should be linking with a |
| just-built one. |
| |
| `depdemo-conf.test' |
| `depdemo-make.test' |
| `depdemo-exec.test' |
| `depdemo-inst.test' |
| `depdemo-unst.test' |
| `depdemo-static.test' |
| `depdemo-static-make.test' |
| `depdemo-static-exec.test' |
| `depdemo-static-inst.test' |
| `depdemo-static-unst.test' |
| `depdemo-shared.test' |
| `depdemo-shared-make.test' |
| `depdemo-shared-exec.test' |
| `depdemo-shared-inst.test' |
| `depdemo-shared-unst.test' |
| `depdemo-nofast.test' |
| `depdemo-nofast-make.test' |
| `depdemo-nofast-exec.test' |
| `depdemo-nofast-inst.test' |
| `depdemo-nofast-unst.test' |
| These programs check to see that the `tests/depdemo' subdirectory |
| of the libtool distribution can be configured, built, installed, |
| and uninstalled correctly. |
| |
| The `tests/depdemo' subdirectory contains a demonstration of |
| inter-library dependencies with libtool. The test programs link |
| some interdependent libraries. |
| |
| The tests matching `depdemo-*make.test', `depdemo-*exec.test', |
| `depdemo-*inst.test' and `depdemo-*unst.test' are executed four |
| times, under four different libtool configurations: |
| `depdemo-conf.test' configures `depdemo/libtool' to build both |
| static and shared libraries, `depdemo-static.test' builds only |
| static libraries (`--disable-shared'), and `depdemo-shared.test' |
| builds only shared libraries (`--disable-static'). |
| `depdemo-nofast.test' configures `depdemo/libtool' to disable the |
| fast-install mode (`--enable-fast-install=no'). |
| |
| `mdemo-conf.test' |
| `mdemo-make.test' |
| `mdemo-exec.test' |
| `mdemo-inst.test' |
| `mdemo-unst.test' |
| `mdemo-static.test' |
| `mdemo-static-make.test' |
| `mdemo-static-exec.test' |
| `mdemo-static-inst.test' |
| `mdemo-static-unst.test' |
| `mdemo-shared.test' |
| `mdemo-shared-make.test' |
| `mdemo-shared-exec.test' |
| `mdemo-shared-inst.test' |
| `mdemo-shared-unst.test' |
| These programs check to see that the `tests/mdemo' subdirectory of |
| the libtool distribution can be configured, built, installed, and |
| uninstalled correctly. |
| |
| The `tests/mdemo' subdirectory contains a demonstration of a |
| package that uses libtool and the system independent dlopen wrapper |
| `libltdl' to load modules. The library `libltdl' provides a |
| dlopen wrapper for various platforms (POSIX) including support for |
| dlpreopened modules (*note Dlpreopening::). |
| |
| The tests matching `mdemo-*make.test', `mdemo-*exec.test', |
| `mdemo-*inst.test' and `mdemo-*unst.test' are executed three |
| times, under three different libtool configurations: |
| `mdemo-conf.test' configures `mdemo/libtool' to build both static |
| and shared libraries, `mdemo-static.test' builds only static |
| libraries (`--disable-shared'), and `mdemo-shared.test' builds |
| only shared libraries (`--disable-static'). |
| |
| `mdemo-dryrun.test' |
| This test checks whether libtool's `--dry-run' mode works properly. |
| |
| `mdemo2-conf.test' |
| `mdemo2-exec.test' |
| `mdemo2-make.test' |
| These programs check to see that the `tests/mdemo2' subdirectory of |
| the libtool distribution can be configured, built, and executed |
| correctly. |
| |
| The `tests/mdemo2' directory contains a demonstration of a package |
| that attempts to link with a library (from the `tests/mdemo' |
| directory) that itself does dlopening of libtool modules. |
| |
| `link.test' |
| This test guarantees that linking directly against a non-libtool |
| static library works properly. |
| |
| `link-2.test' |
| This test makes sure that files ending in `.lo' are never linked |
| directly into a program file. |
| |
| `nomode.test' |
| Check whether we can actually get help for libtool. |
| |
| `objectlist.test' |
| Check that a nonexistent objectlist file is properly detected. |
| |
| `pdemo-conf.test' |
| `pdemo-make.test' |
| `pdemo-exec.test' |
| `pdemo-inst.test' |
| These programs check to see that the `tests/pdemo' subdirectory of |
| the libtool distribution can be configured, built, and executed |
| correctly. |
| |
| The `pdemo-conf.test' lowers the `max_cmd_len' variable in the |
| generated libtool script to test the measures to evade command line |
| length limitations. |
| |
| `quote.test' |
| This program checks libtool's metacharacter quoting. |
| |
| `sh.test' |
| Checks for some nonportable or dubious or undesired shell |
| constructs in shell scripts. |
| |
| `suffix.test' |
| When other programming languages are used with libtool (*note |
| Other languages::), the source files may end in suffixes other |
| than `.c'. This test validates that libtool can handle suffixes |
| for all the file types that it supports, and that it fails when |
| the suffix is invalid. |
| |
| `tagdemo-conf.test' |
| `tagdemo-make.test' |
| `tagdemo-exec.test' |
| `tagdemo-static.test' |
| `tagdemo-static-make.test' |
| `tagdemo-static-exec.test' |
| `tagdemo-shared.test' |
| `tagdemo-shared-make.test' |
| `tagdemo-shared-exec.test' |
| `tagdemo-undef.test' |
| `tagdemo-undef-make.test' |
| `tagdemo-undef-exec.test' |
| These programs check to see that the `tests/tagdemo' subdirectory |
| of the libtool distribution can be configured, built, and executed |
| correctly. |
| |
| The `tests/tagdemo' directory contains a demonstration of a package |
| that uses libtool's multi-language support through configuration |
| tags. It generates a library from C++ sources, which is then |
| linked to a C++ program. |
| |
| `f77demo-conf.test' |
| `f77demo-make.test' |
| `f77demo-exec.test' |
| `f77demo-static.test' |
| `f77demo-static-make.test' |
| `f77demo-static-exec.test' |
| `f77demo-shared.test' |
| `f77demo-shared-make.test' |
| `f77demo-shared-exec.test' |
| These programs check to see that the `tests/f77demo' subdirectory |
| of the libtool distribution can be configured, built, and executed |
| correctly. |
| |
| The `tests/f77demo' tests test Fortran 77 support in libtool by |
| creating libraries from Fortran 77 sources, and mixed Fortran and C |
| sources, and a Fortran 77 program to use the former library, and a |
| C program to use the latter library. |
| |
| `fcdemo-conf.test' |
| `fcdemo-make.test' |
| `fcdemo-exec.test' |
| `fcdemo-static.test' |
| `fcdemo-static-make.test' |
| `fcdemo-static-exec.test' |
| `fcdemo-shared.test' |
| `fcdemo-shared-make.test' |
| `fcdemo-shared-exec.test' |
| These programs check to see that the `tests/fcdemo' subdirectory |
| of the libtool distribution can be configured, built, and executed |
| correctly. |
| |
| The `tests/fcdemo' is similar to the `tests/f77demo' directory, |
| except that Fortran 90 is used in combination with the `FC' |
| interface provided by Autoconf and Automake. |
| |
| |
| The new, Autotest-based test suite uses keywords to classify certain |
| test groups: |
| |
| `CXX' |
| `F77' |
| `FC' |
| `GCJ' |
| The test group exercises one of these `libtool' language tags. |
| |
| `autoconf' |
| `automake' |
| These keywords denote that the respective external program is |
| needed by the test group. The tests are typically skipped if the |
| program is not installed. The `automake' keyword may also denote |
| use of the `aclocal' program. |
| |
| `interactive' |
| This test group may require user interaction on some systems. |
| Typically, this means closing a popup window about a DLL load |
| error on Windows. |
| |
| `libltdl' |
| Denote that the `libltdl' library is exercised by the test group. |
| |
| `libtool' |
| `libtoolize' |
| Denote that the `libtool' or `libtoolize' scripts are exercised by |
| the test group, respectively. |
| |
| `recursive' |
| Denote that this test group may recursively re-invoke the test |
| suite itself, with changed settings and maybe a changed `libtool' |
| script. You may use the `INNER_TESTSUITEFLAGS' variable to pass |
| additional settings to this recursive invocation. Typically, |
| recursive invocations delimit the set of tests with another |
| keyword, for example by passing `-k libtool' right before the |
| expansion of the `INNER_TESTSUITEFLAGS' variable (without an |
| intervening space, so you get the chance for further delimitation). |
| |
| Test groups with the keyword `recursive' should not be denoted with |
| keywords, in order to avoid infinite recursion. As a consequence, |
| recursive test groups themselves should never require user |
| interaction, while the test groups they invoke may do so. |
| |
| There is a convenience target `check-noninteractive' that runs all |
| tests from both test suites that do not cause user interaction on |
| Windows. Conversely, the target `check-interactive' runs the |
| complement of tests and might require closing popup windows about DLL |
| load errors on Windows. |
| |
| |
| File: libtool.info, Node: When tests fail, Prev: Test descriptions, Up: Libtool test suite |
| |
| 14.1.2 When tests fail |
| ---------------------- |
| |
| When the tests in the old test suite are run via `make check', output |
| is caught in per-test `tests/TEST-NAME.log' files and summarized in the |
| `test-suite.log' file. The exit status of each program tells the |
| `Makefile' whether or not the test succeeded. |
| |
| If a test fails, it means that there is either a programming error in |
| libtool, or in the test program itself. |
| |
| To investigate a particular test, you may run it directly, as you |
| would a normal program. When the test is invoked in this way, it |
| produces output that may be useful in determining what the problem is. |
| |
| The new, Autotest-based test suite produces as output a file |
| `tests/testsuite.log' which contains information about failed tests. |
| |
| You can pass options to the test suite through the `make' variable |
| `TESTSUITEFLAGS' (*note The Autoconf Manual: (autoconf)testsuite |
| Invocation.). |
| |
| |
| File: libtool.info, Node: Reporting bugs, Prev: Libtool test suite, Up: Troubleshooting |
| |
| 14.2 Reporting bugs |
| =================== |
| |
| If you think you have discovered a bug in libtool, you should think |
| twice: the libtool maintainer is notorious for passing the buck (or |
| maybe that should be "passing the bug"). Libtool was invented to fix |
| known deficiencies in shared library implementations, so, in a way, most |
| of the bugs in libtool are actually bugs in other operating systems. |
| However, the libtool maintainer would definitely be happy to add support |
| for somebody else's buggy operating system. [I wish there was a good |
| way to do winking smiley-faces in Texinfo.] |
| |
| Genuine bugs in libtool include problems with shell script |
| portability, documentation errors, and failures in the test suite |
| (*note Libtool test suite::). |
| |
| First, check the documentation and help screens to make sure that the |
| behaviour you think is a problem is not already mentioned as a feature. |
| |
| Then, you should read the Emacs guide to reporting bugs (*note |
| Reporting Bugs: (emacs)Bugs.). Some of the details listed there are |
| specific to Emacs, but the principle behind them is a general one. |
| |
| Finally, send a bug report to the Libtool bug reporting address |
| <bug-libtool@gnu.org> with any appropriate _facts_, such as test suite |
| output (*note When tests fail::), all the details needed to reproduce |
| the bug, and a brief description of why you think the behaviour is a |
| bug. Be sure to include the word "libtool" in the subject line, as |
| well as the version number you are using (which can be found by typing |
| `libtool --version'). |
| |
| |
| File: libtool.info, Node: Maintaining, Next: GNU Free Documentation License, Prev: Troubleshooting, Up: Top |
| |
| 15 Maintenance notes for libtool |
| ******************************** |
| |
| This chapter contains information that the libtool maintainer finds |
| important. It will be of no use to you unless you are considering |
| porting libtool to new systems, or writing your own libtool. |
| |
| * Menu: |
| |
| * New ports:: How to port libtool to new systems. |
| * Tested platforms:: When libtool was last tested. |
| * Platform quirks:: Information about different library systems. |
| * libtool script contents:: Configuration information that libtool uses. |
| * Cheap tricks:: Making libtool maintainership easier. |
| |
| |
| File: libtool.info, Node: New ports, Next: Tested platforms, Up: Maintaining |
| |
| 15.1 Porting libtool to new systems |
| =================================== |
| |
| Before you embark on porting libtool to an unsupported system, it is |
| worthwhile to send e-mail to the Libtool mailing list |
| <libtool@gnu.org>, to make sure that you are not duplicating existing |
| work. |
| |
| If you find that any porting documentation is missing, please |
| complain! Complaints with patches and improvements to the |
| documentation, or to libtool itself, are more than welcome. |
| |
| * Menu: |
| |
| * Information sources:: Where to find relevant documentation |
| * Porting inter-library dependencies:: Implementation details explained |
| |
| |
| File: libtool.info, Node: Information sources, Next: Porting inter-library dependencies, Up: New ports |
| |
| 15.1.1 Information sources |
| -------------------------- |
| |
| Once it is clear that a new port is necessary, you'll generally need the |
| following information: |
| |
| canonical system name |
| You need the output of `config.guess' for this system, so that you |
| can make changes to the libtool configuration process without |
| affecting other systems. |
| |
| man pages for `ld' and `cc' |
| These generally describe what flags are used to generate PIC, to |
| create shared libraries, and to link against only static |
| libraries. You may need to follow some cross references to find |
| the information that is required. |
| |
| man pages for `ld.so', `rtld', or equivalent |
| These are a valuable resource for understanding how shared |
| libraries are loaded on the system. |
| |
| man page for `ldconfig', or equivalent |
| This page usually describes how to install shared libraries. |
| |
| output from `ls -l /lib /usr/lib' |
| This shows the naming convention for shared libraries on the |
| system, including which names should be symbolic links. |
| |
| any additional documentation |
| Some systems have special documentation on how to build and install |
| shared libraries. |
| |
| If you know how to program the Bourne shell, then you can complete |
| the port yourself; otherwise, you'll have to find somebody with the |
| relevant skills who will do the work. People on the libtool mailing |
| list are usually willing to volunteer to help you with new ports, so |
| you can send the information to them. |
| |
| To do the port yourself, you'll definitely need to modify the |
| `libtool.m4' macros in order to make platform-specific changes to the |
| configuration process. You should search that file for the `PORTME' |
| keyword, which will give you some hints on what you'll need to change. |
| In general, all that is involved is modifying the appropriate |
| configuration variables (*note libtool script contents::). |
| |
| Your best bet is to find an already-supported system that is similar |
| to yours, and make your changes based on that. In some cases, however, |
| your system will differ significantly from every other supported system, |
| and it may be necessary to add new configuration variables, and modify |
| the `ltmain.in' script accordingly. Be sure to write to the mailing |
| list before you make changes to `ltmain.in', since they may have advice |
| on the most effective way of accomplishing what you want. |
| |
| |
| File: libtool.info, Node: Porting inter-library dependencies, Prev: Information sources, Up: New ports |
| |
| 15.1.2 Porting inter-library dependencies support |
| ------------------------------------------------- |
| |
| Since version 1.2c, libtool has re-introduced the ability to do |
| inter-library dependency on some platforms, thanks to a patch by Toshio |
| Kuratomi <badger@prtr-13.ucsc.edu>. Here's a shortened version of the |
| message that contained his patch: |
| |
| The basic architecture is this: in `libtool.m4', the person who |
| writes libtool makes sure `$deplibs' is included in `$archive_cmds' |
| somewhere and also sets the variable `$deplibs_check_method', and maybe |
| `$file_magic_cmd' when `deplibs_check_method' is file_magic. |
| |
| `deplibs_check_method' can be one of five things: |
| `file_magic [REGEX]' |
| looks in the library link path for libraries that have the right |
| libname. Then it runs `$file_magic_cmd' on the library and checks |
| for a match against the extended regular expression REGEX. When |
| `file_magic_test_file' is set by `libtool.m4', it is used as an |
| argument to `$file_magic_cmd' in order to verify whether the |
| regular expression matches its output, and warn the user otherwise. |
| |
| `test_compile' |
| just checks whether it is possible to link a program out of a list |
| of libraries, and checks which of those are listed in the output of |
| `ldd'. It is currently unused, and will probably be dropped in the |
| future. |
| |
| `pass_all' |
| will pass everything without any checking. This may work on |
| platforms in which code is position-independent by default and |
| inter-library dependencies are properly supported by the dynamic |
| linker, for example, on DEC OSF/1 3 and 4. |
| |
| `none' |
| It causes deplibs to be reassigned `deplibs=""'. That way |
| `archive_cmds' can contain deplibs on all platforms, but not have |
| deplibs used unless needed. |
| |
| `unknown' |
| is the default for all systems unless overridden in `libtool.m4'. |
| It is the same as `none', but it documents that we really don't |
| know what the correct value should be, and we welcome patches that |
| improve it. |
| |
| Then in `ltmain.in' we have the real workhorse: a little |
| initialization and postprocessing (to setup/release variables for use |
| with eval echo libname_spec etc.) and a case statement that decides the |
| method that is being used. This is the real code... I wish I could |
| condense it a little more, but I don't think I can without function |
| calls. I've mostly optimized it (moved things out of loops, etc.) but |
| there is probably some fat left. I thought I should stop while I was |
| ahead, work on whatever bugs you discover, etc. before thinking about |
| more than obvious optimizations. |
| |
| |
| File: libtool.info, Node: Tested platforms, Next: Platform quirks, Prev: New ports, Up: Maintaining |
| |
| 15.2 Tested platforms |
| ===================== |
| |
| This table describes when libtool was last known to be tested on |
| platforms where it claims to support shared libraries: |
| |
| ------------------------------------------------------- |
| canonical host name compiler libtool results |
| (tools versions) release |
| ------------------------------------------------------- |
| alpha-dec-osf5.1 cc 1.3e ok (1.910) |
| alpha-dec-osf4.0f gcc 1.3e ok (1.910) |
| alpha-dec-osf4.0f cc 1.3e ok (1.910) |
| alpha-dec-osf3.2 gcc 0.8 ok |
| alpha-dec-osf3.2 cc 0.8 ok |
| alpha-dec-osf2.1 gcc 1.2f NS |
| alpha*-unknown-linux-gnu gcc 1.3b ok |
| (egcs-1.1.2, GNU ld 2.9.1.0.23) |
| hppa2.0w-hp-hpux11.00 cc 1.2f ok |
| hppa2.0-hp-hpux10.20 cc 1.3.2 ok |
| hppa1.1-hp-hpux10.20 gcc 1.2f ok |
| hppa1.1-hp-hpux10.20 cc 1.3c ok (1.821) |
| hppa1.1-hp-hpux10.10 gcc 1.2f ok |
| hppa1.1-hp-hpux10.10 cc 1.2f ok |
| hppa1.1-hp-hpux9.07 gcc 1.2f ok |
| hppa1.1-hp-hpux9.07 cc 1.2f ok |
| hppa1.1-hp-hpux9.05 gcc 1.2f ok |
| hppa1.1-hp-hpux9.05 cc 1.2f ok |
| hppa1.1-hp-hpux9.01 gcc 1.2f ok |
| hppa1.1-hp-hpux9.01 cc 1.2f ok |
| i*86-*-beos gcc 1.2f ok |
| i*86-*-bsdi4.0.1 gcc 1.3c ok |
| (gcc-2.7.2.1) |
| i*86-*-bsdi4.0 gcc 1.2f ok |
| i*86-*-bsdi3.1 gcc 1.2e NS |
| i*86-*-bsdi3.0 gcc 1.2e NS |
| i*86-*-bsdi2.1 gcc 1.2e NS |
| i*86-pc-cygwin gcc 1.3b NS |
| (egcs-1.1 stock b20.1 compiler) |
| i*86-*-dguxR4.20MU01 gcc 1.2 ok |
| i*86-*-freebsd4.3 gcc 1.3e ok (1.912) |
| i*86-*-freebsdelf4.0 gcc 1.3c ok |
| (egcs-1.1.2) |
| i*86-*-freebsdelf3.2 gcc 1.3c ok |
| (gcc-2.7.2.1) |
| i*86-*-freebsdelf3.1 gcc 1.3c ok |
| (gcc-2.7.2.1) |
| i*86-*-freebsdelf3.0 gcc 1.3c ok |
| i*86-*-freebsd3.0 gcc 1.2e ok |
| i*86-*-freebsd2.2.8 gcc 1.3c ok |
| (gcc-2.7.2.1) |
| i*86-*-freebsd2.2.6 gcc 1.3b ok |
| (egcs-1.1 & gcc-2.7.2.1, native ld) |
| i*86-*-freebsd2.1.5 gcc 0.5 ok |
| i*86-*-netbsd1.5 gcc 1.3e ok (1.901) |
| (egcs-1.1.2) |
| i*86-*-netbsd1.4 gcc 1.3c ok |
| (egcs-1.1.1) |
| i*86-*-netbsd1.4.3A gcc 1.3e ok (1.901) |
| i*86-*-netbsd1.3.3 gcc 1.3c ok |
| (gcc-2.7.2.2+myc2) |
| i*86-*-netbsd1.3.2 gcc 1.2e ok |
| i*86-*-netbsd1.3I gcc 1.2e ok |
| (egcs 1.1?) |
| i*86-*-netbsd1.2 gcc 0.9g ok |
| i*86-*-linux-gnu gcc 1.3e ok (1.901) |
| (Red Hat 7.0, gcc "2.96") |
| i*86-*-linux-gnu gcc 1.3e ok (1.911) |
| (SuSE 7.0, gcc 2.95.2) |
| i*86-*-linux-gnulibc1 gcc 1.2f ok |
| i*86-*-openbsd2.5 gcc 1.3c ok |
| (gcc-2.8.1) |
| i*86-*-openbsd2.4 gcc 1.3c ok |
| (gcc-2.8.1) |
| i*86-*-solaris2.7 gcc 1.3b ok |
| (egcs-1.1.2, native ld) |
| i*86-*-solaris2.6 gcc 1.2f ok |
| i*86-*-solaris2.5.1 gcc 1.2f ok |
| i*86-ncr-sysv4.3.03 gcc 1.2f ok |
| i*86-ncr-sysv4.3.03 cc 1.2e ok |
| (cc -Hnocopyr) |
| i*86-pc-sco3.2v5.0.5 cc 1.3c ok |
| i*86-pc-sco3.2v5.0.5 gcc 1.3c ok |
| (gcc 95q4c) |
| i*86-pc-sco3.2v5.0.5 gcc 1.3c ok |
| (egcs-1.1.2) |
| i*86-sco-sysv5uw7.1.1 gcc 1.3e ok (1.901) |
| (gcc-2.95.2, SCO linker) |
| i*86-UnixWare7.1.0-sysv5 cc 1.3c ok |
| i*86-UnixWare7.1.0-sysv5 gcc 1.3c ok |
| (egcs-1.1.1) |
| m68k-next-nextstep3 gcc 1.2f NS |
| m68k-sun-sunos4.1.1 gcc 1.2f NS |
| (gcc-2.5.7) |
| m88k-dg-dguxR4.12TMU01 gcc 1.2 ok |
| m88k-motorola-sysv4 gcc 1.3 ok |
| (egcs-1.1.2) |
| mips-sgi-irix6.5 gcc 1.2f ok |
| (gcc-2.8.1) |
| mips-sgi-irix6.4 gcc 1.2f ok |
| mips-sgi-irix6.3 gcc 1.3b ok |
| (egcs-1.1.2, native ld) |
| mips-sgi-irix6.3 cc 1.3b ok |
| (cc 7.0) |
| mips-sgi-irix6.2 gcc 1.2f ok |
| mips-sgi-irix6.2 cc 0.9 ok |
| mips-sgi-irix5.3 gcc 1.2f ok |
| (egcs-1.1.1) |
| mips-sgi-irix5.3 gcc 1.2f NS |
| (gcc-2.6.3) |
| mips-sgi-irix5.3 cc 0.8 ok |
| mips-sgi-irix5.2 gcc 1.3b ok |
| (egcs-1.1.2, native ld) |
| mips-sgi-irix5.2 cc 1.3b ok |
| (cc 3.18) |
| mips-sni-sysv4 cc 1.3.5 ok |
| (Siemens C-compiler) |
| mips-sni-sysv4 gcc 1.3.5 ok |
| (gcc-2.7.2.3, GNU assembler 2.8.1, native ld) |
| mipsel-unknown-openbsd2.1 gcc 1.0 ok |
| powerpc-apple-darwin6.4 gcc 1.5 ok |
| (apple dev tools released 12/2002) |
| powerpc-ibm-aix4.3.1.0 gcc 1.2f ok |
| (egcs-1.1.1) |
| powerpc-ibm-aix4.2.1.0 gcc 1.2f ok |
| (egcs-1.1.1) |
| powerpc-ibm-aix4.1.5.0 gcc 1.2f ok |
| (egcs-1.1.1) |
| powerpc-ibm-aix4.1.5.0 gcc 1.2f NS |
| (gcc-2.8.1) |
| powerpc-ibm-aix4.1.4.0 gcc 1.0 ok |
| powerpc-ibm-aix4.1.4.0 xlc 1.0i ok |
| rs6000-ibm-aix4.1.5.0 gcc 1.2f ok |
| (gcc-2.7.2) |
| rs6000-ibm-aix4.1.4.0 gcc 1.2f ok |
| (gcc-2.7.2) |
| rs6000-ibm-aix3.2.5 gcc 1.0i ok |
| rs6000-ibm-aix3.2.5 xlc 1.0i ok |
| sparc-sun-solaris2.8 gcc 1.3e ok (1.913) |
| (gcc-2.95.3 & native ld) |
| sparc-sun-solaris2.7 gcc 1.3e ok (1.913) |
| (gcc-2.95.3 & native ld) |
| sparc-sun-solaris2.6 gcc 1.3e ok (1.913) |
| (gcc-2.95.3 & native ld) |
| sparc-sun-solaris2.5.1 gcc 1.3e ok (1.911) |
| sparc-sun-solaris2.5 gcc 1.3b ok |
| (egcs-1.1.2, GNU ld 2.9.1 & native ld) |
| sparc-sun-solaris2.5 cc 1.3b ok |
| (SC 3.0.1) |
| sparc-sun-solaris2.4 gcc 1.0a ok |
| sparc-sun-solaris2.4 cc 1.0a ok |
| sparc-sun-solaris2.3 gcc 1.2f ok |
| sparc-sun-sunos4.1.4 gcc 1.2f ok |
| sparc-sun-sunos4.1.4 cc 1.0f ok |
| sparc-sun-sunos4.1.3_U1 gcc 1.2f ok |
| sparc-sun-sunos4.1.3C gcc 1.2f ok |
| sparc-sun-sunos4.1.3 gcc 1.3b ok |
| (egcs-1.1.2, GNU ld 2.9.1 & native ld) |
| sparc-sun-sunos4.1.3 cc 1.3b ok |
| sparc-unknown-bsdi4.0 gcc 1.2c ok |
| sparc-unknown-linux-gnulibc1 gcc 1.2f ok |
| sparc-unknown-linux-gnu gcc 1.3b ok |
| (egcs-1.1.2, GNU ld 2.9.1.0.23) |
| sparc64-unknown-linux-gnu gcc 1.2f ok |
| |
| Notes: |
| - "ok" means "all tests passed". |
| - "NS" means "Not Shared", but OK for static libraries |
| |
| Note: The vendor-distributed HP-UX `sed'(1) programs are horribly |
| broken, and cannot handle libtool's requirements, so users may report |
| unusual problems. There is no workaround except to install a working |
| `sed' (such as GNU `sed') on these systems. |
| |
| Note: The vendor-distributed NCR MP-RAS `cc' programs emits |
| copyright on standard error that confuse tests on size of |
| `conftest.err'. The workaround is to specify `CC' when run `configure' |
| with `CC='cc -Hnocopyr''. |
| |
| |
| File: libtool.info, Node: Platform quirks, Next: libtool script contents, Prev: Tested platforms, Up: Maintaining |
| |
| 15.3 Platform quirks |
| ==================== |
| |
| This section is dedicated to the sanity of the libtool maintainers. It |
| describes the programs that libtool uses, how they vary from system to |
| system, and how to test for them. |
| |
| Because libtool is a shell script, it can be difficult to understand |
| just by reading it from top to bottom. This section helps show why |
| libtool does things a certain way. Combined with the scripts |
| themselves, you should have a better sense of how to improve libtool, or |
| write your own. |
| |
| * Menu: |
| |
| * References:: Finding more information. |
| * Compilers:: Creating object files from source files. |
| * Reloadable objects:: Binding object files together. |
| * Multiple dependencies:: Removing duplicate dependent libraries. |
| * Archivers:: Programs that create static archives. |
| * Cross compiling:: Issues that arise when cross compiling. |
| * File name conversion:: Converting file names between platforms. |
| * Windows DLLs:: Windows header defines. |
| |
| |
| File: libtool.info, Node: References, Next: Compilers, Up: Platform quirks |
| |
| 15.3.1 References |
| ----------------- |
| |
| The following is a list of valuable documentation references: |
| |
| * SGI's IRIX Manual Pages can be found at |
| `http://techpubs.sgi.com/cgi-bin/infosrch.cgi?cmd=browse&db=man'. |
| |
| * Sun's free service area |
| (`http://www.sun.com/service/online/free.html') and documentation |
| server (`http://docs.sun.com/'). |
| |
| * Compaq's Tru64 UNIX online documentation is at |
| (`http://tru64unix.compaq.com/faqs/publications/pub_page/doc_list.html') |
| with C++ documentation at |
| (`http://tru64unix.compaq.com/cplus/docs/index.htm'). |
| |
| * Hewlett-Packard has online documentation at |
| (`http://docs.hp.com/index.html'). |
| |
| * IBM has online documentation at |
| (`http://www.rs6000.ibm.com/resource/aix_resource/Pubs/'). |
| |
| |
| File: libtool.info, Node: Compilers, Next: Reloadable objects, Prev: References, Up: Platform quirks |
| |
| 15.3.2 Compilers |
| ---------------- |
| |
| The only compiler characteristics that affect libtool are the flags |
| needed (if any) to generate PIC objects. In general, if a C compiler |
| supports certain PIC flags, then any derivative compilers support the |
| same flags. Until there are some noteworthy exceptions to this rule, |
| this section will document only C compilers. |
| |
| The following C compilers have standard command line options, |
| regardless of the platform: |
| |
| `gcc' |
| This is the GNU C compiler, which is also the system compiler for |
| many free operating systems (FreeBSD, GNU/Hurd, GNU/Linux, Lites, |
| NetBSD, and OpenBSD, to name a few). |
| |
| The `-fpic' or `-fPIC' flags can be used to generate |
| position-independent code. `-fPIC' is guaranteed to generate |
| working code, but the code is slower on m68k, m88k, and Sparc |
| chips. However, using `-fpic' on those chips imposes arbitrary |
| size limits on the shared libraries. |
| |
| The rest of this subsection lists compilers by the operating system |
| that they are bundled with: |
| |
| `aix3*' |
| `aix4*' |
| Most AIX compilers have no PIC flags, since AIX (with the |
| exception of AIX for IA-64) runs on PowerPC and RS/6000 chips. (1) |
| |
| `hpux10*' |
| Use `+Z' to generate PIC. |
| |
| `osf3*' |
| Digital/UNIX 3.x does not have PIC flags, at least not on the |
| PowerPC platform. |
| |
| `solaris2*' |
| Use `-KPIC' to generate PIC. |
| |
| `sunos4*' |
| Use `-PIC' to generate PIC. |
| |
| ---------- Footnotes ---------- |
| |
| (1) All code compiled for the PowerPC and RS/6000 chips |
| (`powerpc-*-*', `powerpcle-*-*', and `rs6000-*-*') is |
| position-independent, regardless of the operating system or compiler |
| suite. So, "regular objects" can be used to build shared libraries on |
| these systems and no special PIC compiler flags are required. |
| |
| |
| File: libtool.info, Node: Reloadable objects, Next: Multiple dependencies, Prev: Compilers, Up: Platform quirks |
| |
| 15.3.3 Reloadable objects |
| ------------------------- |
| |
| On all known systems, a reloadable object can be created by running `ld |
| -r -o OUTPUT.o INPUT1.o INPUT2.o'. This reloadable object may be |
| treated as exactly equivalent to other objects. |
| |
| |
| File: libtool.info, Node: Multiple dependencies, Next: Archivers, Prev: Reloadable objects, Up: Platform quirks |
| |
| 15.3.4 Multiple dependencies |
| ---------------------------- |
| |
| On most modern platforms the order in which dependent libraries are |
| listed has no effect on object generation. In theory, there are |
| platforms that require libraries that provide missing symbols to other |
| libraries to be listed after those libraries whose symbols they provide. |
| |
| Particularly, if a pair of static archives each resolve some of the |
| other's symbols, it might be necessary to list one of those archives |
| both before and after the other one. Libtool does not currently cope |
| with this situation well, since duplicate libraries are removed from |
| the link line by default. Libtool provides the command line option |
| `--preserve-dup-deps' to preserve all duplicate dependencies in cases |
| where it is necessary. |
| |
| |
| File: libtool.info, Node: Archivers, Next: Cross compiling, Prev: Multiple dependencies, Up: Platform quirks |
| |
| 15.3.5 Archivers |
| ---------------- |
| |
| On all known systems, building a static library can be accomplished by |
| running `ar cru libNAME.a OBJ1.o OBJ2.o ...', where the `.a' file is |
| the output library, and each `.o' file is an object file. |
| |
| On all known systems, if there is a program named `ranlib', then it |
| must be used to "bless" the created library before linking against it, |
| with the `ranlib libNAME.a' command. Some systems, like Irix, use the |
| `ar ts' command, instead. |
| |
| |
| File: libtool.info, Node: Cross compiling, Next: File name conversion, Prev: Archivers, Up: Platform quirks |
| |
| 15.3.6 Cross compiling |
| ---------------------- |
| |
| Most build systems support the ability to compile libraries and |
| applications on one platform for use on a different platform, provided |
| a compiler capable of generating the appropriate output is available. |
| In such cross compiling scenarios, the platform on which the libraries |
| or applications are compiled is called the "build platform", while the |
| platform on which the libraries or applications are intended to be used |
| or executed is called the "host platform". *note The GNU Build System: |
| (automake)GNU Build System, of which libtool is a part, supports cross |
| compiling via arguments passed to the configure script: `--build=...' |
| and `--host=...'. However, when the build platform and host platform |
| are very different, libtool is required to make certain accommodations |
| to support these scenarios. |
| |
| In most cases, because the build platform and host platform differ, |
| the cross-compiled libraries and executables can't be executed or |
| tested on the build platform where they were compiled. The testsuites |
| of most build systems will often skip any tests that involve executing |
| such foreign executables when cross-compiling. However, if the build |
| platform and host platform are sufficiently similar, it is often |
| possible to run cross-compiled applications. Libtool's own testsuite |
| often attempts to execute cross-compiled tests, but will mark any |
| failures as _skipped_ since the failure might simply be due to the |
| differences between the two platforms. |
| |
| In addition to cases where the host platform and build platform are |
| extremely similar (e.g. `i586-pc-linux-gnu' and `i686-pc-linux-gnu'), |
| there is another case in which cross-compiled host applications may be |
| executed on the build platform. This is possible when the build |
| platform supports an emulation or API-enhanced environment for the host |
| platform. One example of this situation would be if the build platform |
| were MinGW, and the host platform were Cygwin (or vice versa). Both of |
| these platforms can actually operate within a single Windows instance, |
| so Cygwin applications can be launched from a MinGW context, and vice |
| versa--provided certain care is taken. Another example would be if the |
| build platform were GNU/Linux on an x86 32bit processor, and the host |
| platform were MinGW. In this situation, the Wine |
| (http://www.winehq.org/) environment can be used to launch Windows |
| applications from the GNU/Linux operating system; again, provided |
| certain care is taken. |
| |
| One particular issue occurs when a Windows platform such as MinGW, |
| Cygwin, or MSYS is the host or build platform, while the other platform |
| is a Unix-style system. In these cases, there are often conflicts |
| between the format of the file names and paths expected within host |
| platform libraries and executables, and those employed on the build |
| platform. |
| |
| This situation is best described using a concrete example: suppose |
| the build platform is GNU/Linux with canonical triplet |
| `i686-pc-linux-gnu'. Suppose further that the host platform is MinGW |
| with canonical triplet `i586-pc-mingw32'. On the GNU/Linux platform |
| there is a cross compiler following the usual naming conventions of |
| such compilers, where the compiler name is prefixed by the host |
| canonical triplet (or suitable alias). (For more information |
| concerning canonical triplets and platform aliases, see *note |
| Specifying Target Triplets: (autoconf)Specifying Target Triplets. and |
| *note Canonicalizing: (autoconf)Canonicalizing.) In this case, the C |
| compiler is named `i586-pc-mingw32-gcc'. |
| |
| As described in *note Wrapper executables::, for the MinGW host |
| platform libtool uses a wrapper executable to set various environment |
| variables before launching the actual program executable. Like the |
| program executable, the wrapper executable is cross-compiled for the |
| host platform (that is, for MinGW). As described above, ordinarily a |
| host platform executable cannot be executed on the build platform, but |
| in this case the Wine environment could be used to launch the MinGW |
| application from GNU/Linux. However, the wrapper executable, as a host |
| platform (MinGW) application, must set the `PATH' variable so that the |
| true application's dependent libraries can be located--but the contents |
| of the `PATH' variable must be structured for MinGW. Libtool must use |
| the Wine file name mapping facilities to determine the correct value so |
| that the wrapper executable can set the `PATH' variable to point to the |
| correct location. |
| |
| For example, suppose we are compiling an application in `/var/tmp' on |
| GNU/Linux, using separate source code and build directories: |
| |
| `/var/tmp/foo-1.2.3/app/' (application source code) |
| `/var/tmp/foo-1.2.3/lib/' (library source code) |
| `/var/tmp/BUILD/app/' (application build objects here) |
| `/var/tmp/BUILD/lib/' (library build objects here) |
| |
| Since the library will be built in `/var/tmp/BUILD/lib', the wrapper |
| executable (which will be in `/var/tmp/BUILD/app') must add that |
| directory to `PATH' (actually, it must add the directory named OBJDIR |
| under `/var/tmp/BUILD/lib', but we'll ignore that detail for now). |
| However, Windows does not have a concept of Unix-style file or |
| directory names such as `/var/tmp/BUILD/lib'. Therefore, Wine provides |
| a mapping from Windows file names such as `C:\Program Files' to specific |
| Unix-style file names. Wine also provides a utility that can be used |
| to map Unix-style file names to Windows file names. |
| |
| In this case, the wrapper executable should actually add the value |
| |
| Z:\var\tmp\BUILD\lib |
| |
| to the `PATH'. libtool contains support for path conversions of this |
| type, for a certain limited set of build and host platform |
| combinations. In this case, libtool will invoke Wine's `winepath' |
| utility to ensure that the correct `PATH' value is used. For more |
| information, see *note File name conversion::. |
| |
| |
| File: libtool.info, Node: File name conversion, Next: Windows DLLs, Prev: Cross compiling, Up: Platform quirks |
| |
| 15.3.7 File name conversion |
| --------------------------- |
| |
| In certain situations, libtool must convert file names and paths between |
| formats appropriate to different platforms. Usually this occurs when |
| cross-compiling, and affects only the ability to launch host platform |
| executables on the build platform using an emulation or API-enhancement |
| environment such as Wine. Failure to convert paths (*note File Name |
| Conversion Failure::) will cause a warning to be issued, but rarely |
| causes the build to fail--and should have no affect on the compiled |
| products, once installed properly on the host platform. For more |
| information, *note Cross compiling::. |
| |
| However, file name conversion may also occur in another scenario: |
| when using a Unix emulation system on Windows (such as Cygwin or MSYS), |
| combined with a native Windows compiler such as MinGW or MSVC. Only a |
| limited set of such scenarios are currently supported; in other cases |
| file name conversion is skipped. The lack of file name conversion |
| usually means that uninstalled executables can't be launched, but only |
| rarely causes the build to fail (*note File Name Conversion Failure::). |
| |
| libtool supports file name conversion in the following scenarios: |
| |
| build platform host platform Notes |
| --------------------------------------------------------------------------- |
| MinGW (MSYS) MinGW (Windows) *note Native MinGW File Name |
| Conversion:: |
| Cygwin MinGW (Windows) *note Cygwin/Windows File Name |
| Conversion:: |
| Unix + Wine MinGW (Windows) Requires Wine. *note Unix/Windows |
| File Name Conversion:: |
| MinGW (MSYS) Cygwin Requires `LT_CYGPATH'. *note |
| LT_CYGPATH::. Provided for testing |
| purposes only. |
| Unix + Wine Cygwin Requires both Wine and |
| `LT_CYGPATH', but does not yet work |
| with Cygwin 1.7.7 and Wine-1.2. |
| See *note Unix/Windows File Name |
| Conversion:: and *note LT_CYGPATH::. |
| |
| * Menu: |
| |
| * File Name Conversion Failure:: What happens when file name conversion fails |
| * Native MinGW File Name Conversion:: MSYS file name conversion idiosyncrasies |
| * Cygwin/Windows File Name Conversion:: Using `cygpath' to convert Cygwin file names |
| * Unix/Windows File Name Conversion:: Using Wine to convert Unix paths |
| * LT_CYGPATH:: Invoking `cygpath' from other environments |
| * Cygwin to MinGW Cross:: Other notes concerning MinGW cross |
| |
| |
| File: libtool.info, Node: File Name Conversion Failure, Next: Native MinGW File Name Conversion, Up: File name conversion |
| |
| 15.3.7.1 File Name Conversion Failure |
| ..................................... |
| |
| In most cases, file name conversion is not needed or attempted. |
| However, when libtool detects that a specific combination of build and |
| host platform does require file name conversion, it is possible that |
| the conversion may fail. In these cases, you may see a warning such as |
| the following: |
| |
| Could not determine the host file name corresponding to |
| `... a file name ...' |
| Continuing, but uninstalled executables may not work. |
| |
| or |
| |
| Could not determine the host path corresponding to |
| `... a path ...' |
| Continuing, but uninstalled executables may not work. |
| |
| This should not cause the build to fail. At worst, it means that the |
| wrapper executable will specify file names or paths appropriate for the |
| build platform. Since those are not appropriate for the host platform, |
| the uninstalled executables would not operate correctly, even when the |
| wrapper executable is launched via the appropriate emulation or |
| API-enhancement (e.g. Wine). Simply install the executables on the |
| host platform, and execute them there. |
| |
| |
| File: libtool.info, Node: Native MinGW File Name Conversion, Next: Cygwin/Windows File Name Conversion, Prev: File Name Conversion Failure, Up: File name conversion |
| |
| 15.3.7.2 Native MinGW File Name Conversion |
| .......................................... |
| |
| MSYS is a Unix emulation environment for Windows, and is specifically |
| designed such that in normal usage it _pretends_ to be MinGW or native |
| Windows, but understands Unix-style file names and paths, and supports |
| standard Unix tools and shells. Thus, "native" MinGW builds are |
| actually an odd sort of cross-compile, from an MSYS Unix emulation |
| environment "pretending" to be MinGW, to actual native Windows. |
| |
| When an MSYS shell launches a native Windows executable (as opposed |
| to other _MSYS_ executables), it uses a system of heuristics to detect |
| any command-line arguments that contain file names or paths. It |
| automatically converts these file names from the MSYS (Unix-like) |
| format, to the corresponding Windows file name, before launching the |
| executable. However, this auto-conversion facility is only available |
| when using the MSYS runtime library. The wrapper executable itself is |
| a MinGW application (that is, it does not use the MSYS runtime |
| library). The wrapper executable must set `PATH' to, and call |
| `_spawnv' with, values that have already been converted from MSYS |
| format to Windows. Thus, when libtool writes the source code for the |
| wrapper executable, it must manually convert MSYS paths to Windows |
| format, so that the Windows values can be hard-coded into the wrapper |
| executable. |
| |
| |
| File: libtool.info, Node: Cygwin/Windows File Name Conversion, Next: Unix/Windows File Name Conversion, Prev: Native MinGW File Name Conversion, Up: File name conversion |
| |
| 15.3.7.3 Cygwin/Windows File Name Conversion |
| ............................................ |
| |
| Cygwin provides a Unix emulation environment for Windows. As part of |
| that emulation, it provides a file system mapping that presents the |
| Windows file system in a Unix-compatible manner. Cygwin also provides |
| a utility `cygpath' that can be used to convert file names and paths |
| between the two representations. In a correctly configured Cygwin |
| installation, `cygpath' is always present, and is in the `PATH'. |
| |
| Libtool uses `cygpath' to convert from Cygwin (Unix-style) file names |
| and paths to Windows format when the build platform is Cygwin and the |
| host platform is MinGW. |
| |
| When the host platform is Cygwin, but the build platform is MSYS or |
| some Unix system, libtool also uses `cygpath' to convert from Windows |
| to Cygwin format (after first converting from the build platform format |
| to Windows format; see *note Native MinGW File Name Conversion:: and |
| *note Unix/Windows File Name Conversion::). Because the build platform |
| is not Cygwin, `cygpath' is not (and should not be) in the `PATH'. |
| Therefore, in this configuration the environment variable `LT_CYGPATH' |
| is required. *Note LT_CYGPATH::. |
| |
| |
| File: libtool.info, Node: Unix/Windows File Name Conversion, Next: LT_CYGPATH, Prev: Cygwin/Windows File Name Conversion, Up: File name conversion |
| |
| 15.3.7.4 Unix/Windows File Name Conversion |
| .......................................... |
| |
| Wine (http://www.winehq.org/) provides an interpretation environment for |
| some Unix platforms in which Windows applications can be executed. It |
| provides a mapping between the Unix file system and a virtual Windows |
| file system used by the Windows programs. For the file name conversion |
| to work, Wine must be installed and properly configured on the build |
| platform, and the `winepath' application must be in the build |
| platform's `PATH'. In addition, on 32bit GNU/Linux it is usually |
| helpful if the binfmt extension is enabled. |
| |
| |
| File: libtool.info, Node: LT_CYGPATH, Next: Cygwin to MinGW Cross, Prev: Unix/Windows File Name Conversion, Up: File name conversion |
| |
| 15.3.7.5 LT_CYGPATH |
| ................... |
| |
| For some cross-compile configurations (where the host platform is |
| Cygwin), the `cygpath' program is used to convert file names from the |
| build platform notation to the Cygwin form (technically, this |
| conversion is from Windows notation to Cygwin notation; the conversion |
| from the build platform format to Windows notation is performed via |
| other means). However, because the `cygpath' program is not (and |
| should not be) in the `PATH' on the build platform, `LT_CYGPATH' must |
| specify the full build platform file name (that is, the full Unix or |
| MSYS file name) of the `cygpath' program. |
| |
| The reason `cygpath' should not be in the build platform `PATH' is |
| twofold: first, `cygpath' is usually installed in the same directory as |
| many other Cygwin executables, such as `sed', `cp', etc. If the build |
| platform environment had this directory in its `PATH', then these |
| Cygwin versions of common Unix utilities might be used in preference to |
| the ones provided by the build platform itself, with deleterious |
| effects. Second, especially when Cygwin-1.7 or later is used, multiple |
| Cygwin installations can coexist within the same Windows instance. |
| Each installation will have separate "mount tables" specified in |
| `CYGROOT-N/etc/fstab'. These "mount tables" control how that instance |
| of Cygwin will map Windows file names and paths to Cygwin form. Each |
| installation's `cygpath' utility automatically deduces the appropriate |
| `/etc/fstab' file. Since each `CYGROOT-N/etc/fstab' mount table may |
| specify different mappings, it matters which `cygpath' is used. |
| |
| Note that `cygpath' is a Cygwin application; to execute this tool |
| from Unix requires a working and properly configured Wine installation, |
| as well as enabling the GNU/Linux `binfmt' extension. Furthermore, the |
| Cygwin `setup.exe' tool should have been used, via Wine, to properly |
| install Cygwin into the Wine file system (and registry). |
| |
| Unfortunately, Wine support for Cygwin is intermittent. Recent |
| releases of Cygwin (1.7 and above) appear to require more Windows API |
| support than Wine provides (as of Wine version 1.2); most Cygwin |
| applications fail to execute. This includes `cygpath' itself. Hence, |
| it is best _not_ to use the LT_CYGPATH machinery in libtool when |
| performing Unix to Cygwin cross-compiles. Similarly, it is best _not_ |
| to enable the GNU/Linux binfmt support in this configuration, because |
| while Wine will fail to execute the compiled Cygwin applications, it |
| will still exit with status zero. This tends to confuse build systems |
| and test suites (including libtool's own testsuite, resulting in |
| spurious reported failures). Wine support for the older Cygwin-1.5 |
| series appears satisfactory, but the Cygwin team no longer supports |
| Cygwin-1.5. It is hoped that Wine will eventually be improved such that |
| Cygwin-1.7 will again operate correctly under Wine. Until then, |
| libtool will report warnings as described in *note File Name Conversion |
| Failure:: in these scenarios. |
| |
| However, `LT_CYGPATH' is also used for the MSYS to Cygwin cross |
| compile scenario, and operates as expected. |
| |
| |
| File: libtool.info, Node: Cygwin to MinGW Cross, Prev: LT_CYGPATH, Up: File name conversion |
| |
| 15.3.7.6 Cygwin to MinGW Cross |
| .............................. |
| |
| There are actually three different scenarios that could all |
| legitimately be called a "Cygwin to MinGW" cross compile. The current |
| (and standard) definition is when there is a compiler that produces |
| native Windows libraries and applications, but which itself is a Cygwin |
| application, just as would be expected in any other cross compile setup. |
| |
| However, historically there were two other definitions, which we |
| will refer to as the _fake_ one, and the _lying_ one. |
| |
| In the _fake_ Cygwin to MinGW cross compile case, you actually use a |
| native MinGW compiler, but you do so from within a Cygwin environment: |
| |
| export PATH="/c/MinGW/bin:${PATH}" |
| configure --build=i686-pc-cygwin \ |
| --host=mingw32 \ |
| NM=/c/MinGW/bin/nm.exe |
| |
| In this way, the build system "knows" that you are cross compiling, |
| and the file name conversion logic will be used. However, because the |
| tools (`mingw32-gcc', `nm', `ar') used are actually native Windows |
| applications, they will not understand any Cygwin (that is, Unix-like) |
| absolute file names passed as command line arguments (and, unlike MSYS, |
| Cygwin does not automatically convert such arguments). However, so |
| long as only relative file names are used in the build system, and |
| non-Windows-supported Unix idioms such as symlinks and mount points are |
| avoided, this scenario should work. |
| |
| If you must use absolute file names, you will have to force Libtool |
| to convert file names for the toolchain in this case, by doing the |
| following before you run configure: |
| |
| export lt_cv_to_tool_file_cmd=func_convert_file_cygwin_to_w32 |
| |
| In the _lying_ Cygwin to MinGW cross compile case, you lie to the |
| build system: |
| |
| export PATH="/c/MinGW/bin:${PATH}" |
| configure --build=i686-pc-mingw32 \ |
| --host=i686-pc-mingw32 \ |
| --disable-dependency-tracking |
| |
| and claim that the build platform is MinGW, even though you are actually |
| running under _Cygwin_ and not MinGW. In this case, libtool does _not_ |
| know that you are performing a cross compile, and thinks instead that |
| you are performing a native MinGW build. However, as described in |
| (*note Native MinGW File Name Conversion::), that scenario triggers an |
| "MSYS to Windows" file name conversion. This, of course, is the wrong |
| conversion since we are actually running under Cygwin. Also, the |
| toolchain is expecting Windows file names (not Cygwin) but unless told |
| so Libtool will feed Cygwin file names to the toolchain in this case. |
| To force the correct file name conversions in this situation, you |
| should do the following _before_ running configure: |
| |
| export lt_cv_to_host_file_cmd=func_convert_file_cygwin_to_w32 |
| export lt_cv_to_tool_file_cmd=func_convert_file_cygwin_to_w32 |
| |
| Note that this relies on internal implementation details of libtool, |
| and is subject to change. Also, `--disable-dependency-tracking' is |
| required, because otherwise the MinGW GCC will generate dependency |
| files that contain Windows file names. This, in turn, will confuse the |
| Cygwin `make' program, which does not accept Windows file names: |
| |
| Makefile:1: *** target pattern contains no `%'. Stop. |
| |
| There have also always been a number of other details required for |
| the _lying_ case to operate correctly, such as the use of so-called |
| "identity mounts": |
| |
| # CYGWIN-ROOT/etc/fstab |
| D:/foo /foo some_fs binary 0 0 |
| D:/bar /bar some_fs binary 0 0 |
| E:/grill /grill some_fs binary 0 0 |
| |
| In this way, top-level directories of each drive are available using |
| identical names within Cygwin. |
| |
| Note that you also need to ensure that the standard Unix directories |
| (like `/bin', `/lib', `/usr', `/etc') appear in the root of a drive. |
| This means that you must install Cygwin itself into the `C:/' root |
| directory (or `D:/', or `E:/', etc)--instead of the recommended |
| installation into `C:/cygwin/'. In addition, all file names used in |
| the build system must be relative, symlinks should not be used within |
| the source or build directory trees, and all `-M*' options to `gcc' |
| except `-MMD' must be avoided. |
| |
| This is quite a fragile setup, but it has been in historical use, |
| and so is documented here. |
| |
| |
| File: libtool.info, Node: Windows DLLs, Prev: File name conversion, Up: Platform quirks |
| |
| 15.3.8 Windows DLLs |
| ------------------- |
| |
| This topic describes a couple of ways to portably create Windows Dynamic |
| Link Libraries (DLLs). Libtool knows how to create DLLs using GNU tools |
| and using Microsoft tools. |
| |
| A typical library has a "hidden" implementation with an interface |
| described in a header file. On just about every system, the interface |
| could be something like this: |
| |
| Example `foo.h': |
| |
| #ifndef FOO_H |
| #define FOO_H |
| |
| int one (void); |
| int two (void); |
| extern int three; |
| |
| #endif /* FOO_H */ |
| |
| And the implementation could be something like this: |
| |
| Example `foo.c': |
| |
| #include "foo.h" |
| |
| int one (void) |
| { |
| return 1; |
| } |
| |
| int two (void) |
| { |
| return three - one (); |
| } |
| |
| int three = 3; |
| |
| When using contemporary GNU tools to create the Windows DLL, the |
| above code will work there too, thanks to its auto-import/auto-export |
| features. But that is not the case when using older GNU tools or |
| perhaps more interestingly when using proprietary tools. In those |
| cases the code will need additional decorations on the interface |
| symbols with `__declspec(dllimport)' and `__declspec(dllexport)' |
| depending on whether the library is built or it's consumed and how it's |
| built and consumed. However, it should be noted that it would have |
| worked also with Microsoft tools, if only the variable `three' hadn't |
| been there, due to the fact the Microsoft tools will automatically |
| import functions (but sadly not variables) and Libtool will |
| automatically export non-static symbols as described next. |
| |
| With Microsoft tools, Libtool digs through the object files that |
| make up the library, looking for non-static symbols to automatically |
| export. I.e., Libtool with Microsoft tools tries to mimic the |
| auto-export feature of contemporary GNU tools. It should be noted that |
| the GNU auto-export feature is turned off when an explicit |
| `__declspec(dllexport)' is seen. The GNU tools do this to not make |
| more symbols visible for projects that have already taken the trouble |
| to decorate symbols. There is no similar way to limit which symbols |
| are visible in the code when Libtool is using Microsoft tools. In |
| order to limit symbol visibility in that case you need to use one of |
| the options `-export-symbols' or `-export-symbols-regex'. |
| |
| No matching help with auto-import is provided by Libtool, which is |
| why variables must be decorated to import them from a DLL for |
| everything but contemporary GNU tools. As stated above, functions are |
| automatically imported by both contemporary GNU tools and Microsoft |
| tools, but for other proprietary tools the auto-import status of |
| functions is unknown. |
| |
| When the objects that form the library are built, there are generally |
| two copies built for each object. One copy is used when linking the DLL |
| and one copy is used for the static library. On Windows systems, a pair |
| of defines are commonly used to discriminate how the interface symbols |
| should be decorated. The first define is `-DDLL_EXPORT' which is |
| automatically provided by Libtool when `libtool' builds the copy of the |
| object that is destined for the DLL. The second define is |
| `-DLIBFOO_BUILD' (or similar) which is often added by the package |
| providing the library and is used when building the library, but not |
| when consuming the library. |
| |
| However, the matching double compile is not performed when consuming |
| libraries. It is therefore not possible to reliably distinguish if the |
| consumer is importing from a DLL or if it is going to use a static |
| library. |
| |
| With contemporary GNU tools, auto-import often saves the day, but see |
| the GNU ld documentation and its `--enable-auto-import' option for some |
| corner cases when it does not (*note `--enable-auto-import': |
| (ld)Options.). |
| |
| With Microsoft tools you typically get away with always compiling the |
| code such that variables are expected to be imported from a DLL and |
| functions are expected to be found in a static library. The tools will |
| then automatically import the function from a DLL if that is where they |
| are found. If the variables are not imported from a DLL as expected, |
| but are found in a static library that is otherwise pulled in by some |
| function, the linker will issue a warning (LNK4217) that a locally |
| defined symbol is imported, but it still works. In other words, this |
| scheme will not work to only consume variables from a library. There is |
| also a price connected to this liberal use of imports in that an extra |
| indirection is introduced when you are consuming the static version of |
| the library. That extra indirection is unavoidable when the DLL is |
| consumed, but it is not needed when consuming the static library. |
| |
| For older GNU tools and other proprietary tools there is no generic |
| way to make it possible to consume either of the DLL or the static |
| library without user intervention, the tools need to be told what is |
| intended. One common assumption is that if a DLL is being built |
| (`DLL_EXPORT' is defined) then that DLL is going to consume any |
| dependent libraries as DLLs. If that assumption is made everywhere, it |
| is possible to select how an end-user application is consuming |
| libraries by adding a single flag `-DDLL_EXPORT' when a DLL build is |
| required. This is of course an all or nothing deal, either everything |
| as DLLs or everything as static libraries. |
| |
| To sum up the above, the header file of the foo library needs to be |
| changed into something like this: |
| |
| Modified `foo.h': |
| |
| #ifndef FOO_H |
| #define FOO_H |
| |
| #if defined _WIN32 && !defined __GNUC__ |
| # ifdef LIBFOO_BUILD |
| # ifdef DLL_EXPORT |
| # define LIBFOO_SCOPE __declspec (dllexport) |
| # define LIBFOO_SCOPE_VAR extern __declspec (dllexport) |
| # endif |
| # elif defined _MSC_VER |
| # define LIBFOO_SCOPE |
| # define LIBFOO_SCOPE_VAR extern __declspec (dllimport) |
| # elif defined DLL_EXPORT |
| # define LIBFOO_SCOPE __declspec (dllimport) |
| # define LIBFOO_SCOPE_VAR extern __declspec (dllimport) |
| # endif |
| #endif |
| #ifndef LIBFOO_SCOPE |
| # define LIBFOO_SCOPE |
| # define LIBFOO_SCOPE_VAR extern |
| #endif |
| |
| LIBFOO_SCOPE int one (void); |
| LIBFOO_SCOPE int two (void); |
| LIBFOO_SCOPE_VAR int three; |
| |
| #endif /* FOO_H */ |
| |
| When the targets are limited to contemporary GNU tools and Microsoft |
| tools, the above can be simplified to the following: |
| |
| Simplified `foo.h': |
| |
| #ifndef FOO_H |
| #define FOO_H |
| |
| #if defined _WIN32 && !defined __GNUC__ && !defined LIBFOO_BUILD |
| # define LIBFOO_SCOPE_VAR extern __declspec (dllimport) |
| #else |
| # define LIBFOO_SCOPE_VAR extern |
| #endif |
| |
| int one (void); |
| int two (void); |
| LIBFOO_SCOPE_VAR int three; |
| |
| #endif /* FOO_H */ |
| |
| This last simplified version can of course only work when Libtool is |
| used to build the DLL, as no symbols would be exported otherwise (i.e., |
| when using Microsoft tools). |
| |
| It should be noted that there are various projects that attempt to |
| relax these requirements by various low level tricks, but they are not |
| discussed here. Examples are FlexDLL |
| (http://alain.frisch.fr/flexdll.html) and edll |
| (http://edll.sourceforge.net/). |
| |
| |
| File: libtool.info, Node: libtool script contents, Next: Cheap tricks, Prev: Platform quirks, Up: Maintaining |
| |
| 15.4 `libtool' script contents |
| ============================== |
| |
| Since version 1.4, the `libtool' script is generated by `configure' |
| (*note Configuring::). In earlier versions, `configure' achieved this |
| by calling a helper script called `ltconfig'. From libtool version 0.7 |
| to 1.0, this script simply set shell variables, then sourced the |
| libtool backend, `ltmain.sh'. `ltconfig' from libtool version 1.1 |
| through 1.3 inlined the contents of `ltmain.sh' into the generated |
| `libtool', which improved performance on many systems. The tests that |
| `ltconfig' used to perform are now kept in `libtool.m4' where they can |
| be written using Autoconf. This has the runtime performance benefits |
| of inlined `ltmain.sh', _and_ improves the build time a little while |
| considerably easing the amount of raw shell code that used to need |
| maintaining. |
| |
| The convention used for naming variables that hold shell commands for |
| delayed evaluation, is to use the suffix `_cmd' where a single line of |
| valid shell script is needed, and the suffix `_cmds' where multiple |
| lines of shell script *may* be delayed for later evaluation. By |
| convention, `_cmds' variables delimit the evaluation units with the `~' |
| character where necessary. |
| |
| Here is a listing of each of the configuration variables, and how |
| they are used within `ltmain.sh' (*note Configuring::): |
| |
| -- Variable: AR |
| The name of the system library archiver. |
| |
| -- Variable: CC |
| The name of the compiler used to configure libtool. This will |
| always contain the compiler for the current language (*note |
| Tags::). |
| |
| -- Variable: ECHO |
| An `echo' program that does not interpret backslashes as an escape |
| character. It may be given only one argument, so due quoting is |
| necessary. |
| |
| -- Variable: LD |
| The name of the linker that libtool should use internally for |
| reloadable linking and possibly shared libraries. |
| |
| -- Variable: LTCC |
| -- Variable: LTCFLAGS |
| The name of the C compiler and C compiler flags used to configure |
| libtool. |
| |
| -- Variable: NM |
| The name of a BSD- or MS-compatible program that produces listings |
| of global symbols. For BSD `nm', the symbols should be in one the |
| following formats: |
| |
| ADDRESS C GLOBAL-VARIABLE-NAME |
| ADDRESS D GLOBAL-VARIABLE-NAME |
| ADDRESS T GLOBAL-FUNCTION-NAME |
| |
| For MS `dumpbin', the symbols should be in one of the following |
| formats: |
| |
| COUNTER SIZE UNDEF notype External | GLOBAL-VAR |
| COUNTER ADDRESS SECTION notype External | GLOBAL-VAR |
| COUNTER ADDRESS SECTION notype () External | GLOBAL-FUNC |
| |
| The SIZE of the global variables are not zero and the SECTION of |
| the global functions are not "UNDEF". Symbols in "pick any" |
| sections ("pick any" appears in the section header) are not global |
| either. |
| |
| -- Variable: RANLIB |
| Set to the name of the `ranlib' program, if any. |
| |
| -- Variable: allow_undefined_flag |
| The flag that is used by `archive_cmds' in order to declare that |
| there will be unresolved symbols in the resulting shared library. |
| Empty, if no such flag is required. Set to `unsupported' if there |
| is no way to generate a shared library with references to symbols |
| that aren't defined in that library. |
| |
| -- Variable: always_export_symbols |
| Whether libtool should automatically generate a list of exported |
| symbols using `export_symbols_cmds' before linking an archive. |
| Set to `yes' or `no'. Default is `no'. |
| |
| -- Variable: archive_cmds |
| -- Variable: archive_expsym_cmds |
| -- Variable: old_archive_cmds |
| Commands used to create shared libraries, shared libraries with |
| `-export-symbols' and static libraries, respectively. |
| |
| -- Variable: archiver_list_spec |
| Specify filename containing input files for `AR'. |
| |
| -- Variable: old_archive_from_new_cmds |
| If the shared library depends on a static library, |
| `old_archive_from_new_cmds' contains the commands used to create |
| that static library. If this variable is not empty, |
| `old_archive_cmds' is not used. |
| |
| -- Variable: old_archive_from_expsyms_cmds |
| If a static library must be created from the export symbol list in |
| order to correctly link with a shared library, |
| `old_archive_from_expsyms_cmds' contains the commands needed to |
| create that static library. When these commands are executed, the |
| variable `soname' contains the name of the shared library in |
| question, and the `$objdir/$newlib' contains the path of the |
| static library these commands should build. After executing these |
| commands, libtool will proceed to link against `$objdir/$newlib' |
| instead of `soname'. |
| |
| -- Variable: lock_old_archive_extraction |
| Set to `yes' if the extraction of a static library requires locking |
| the library file. This is required on Darwin. |
| |
| -- Variable: build |
| -- Variable: build_alias |
| -- Variable: build_os |
| Set to the specified and canonical names of the system that |
| libtool was built on. |
| |
| -- Variable: build_libtool_libs |
| Whether libtool should build shared libraries on this system. Set |
| to `yes' or `no'. |
| |
| -- Variable: build_old_libs |
| Whether libtool should build static libraries on this system. Set |
| to `yes' or `no'. |
| |
| -- Variable: compiler_c_o |
| Whether the compiler supports the `-c' and `-o' options |
| simultaneously. Set to `yes' or `no'. |
| |
| -- Variable: compiler_needs_object |
| Whether the compiler has to see an object listed on the command |
| line in order to successfully invoke the linker. If `no', then a |
| set of convenience archives or a set of object file names can be |
| passed via linker-specific options or linker scripts. |
| |
| -- Variable: dlopen_support |
| Whether `dlopen' is supported on the platform. Set to `yes' or |
| `no'. |
| |
| -- Variable: dlopen_self |
| Whether it is possible to `dlopen' the executable itself. Set to |
| `yes' or `no'. |
| |
| -- Variable: dlopen_self_static |
| Whether it is possible to `dlopen' the executable itself, when it |
| is linked statically (`-all-static'). Set to `yes' or `no'. |
| |
| -- Variable: exclude_expsyms |
| List of symbols that should not be listed in the preloaded symbols. |
| |
| -- Variable: export_dynamic_flag_spec |
| Compiler link flag that allows a dlopened shared library to |
| reference symbols that are defined in the program. |
| |
| -- Variable: export_symbols_cmds |
| Commands to extract exported symbols from `libobjs' to the file |
| `export_symbols'. |
| |
| -- Variable: extract_expsyms_cmds |
| Commands to extract the exported symbols list from a shared |
| library. These commands are executed if there is no file |
| `$objdir/$soname-def', and should write the names of the exported |
| symbols to that file, for the use of |
| `old_archive_from_expsyms_cmds'. |
| |
| -- Variable: fast_install |
| Determines whether libtool will privilege the installer or the |
| developer. The assumption is that installers will seldom run |
| programs in the build tree, and the developer will seldom install. |
| This is only meaningful on platforms where |
| `shlibpath_overrides_runpath' is not `yes', so `fast_install' will |
| be set to `needless' in this case. If `fast_install' set to |
| `yes', libtool will create programs that search for installed |
| libraries, and, if a program is run in the build tree, a new copy |
| will be linked on-demand to use the yet-to-be-installed libraries. |
| If set to `no', libtool will create programs that use the |
| yet-to-be-installed libraries, and will link a new copy of the |
| program at install time. The default value is `yes' or |
| `needless', depending on platform and configuration flags, and it |
| can be turned from `yes' to `no' with the configure flag |
| `--disable-fast-install'. |
| |
| On some systems, the linker always hardcodes paths to dependent |
| libraries into the output. In this case, `fast_install' is never |
| set to `yes', and relinking at install time is triggered. This |
| also means that `DESTDIR' installation does not work as expected. |
| |
| -- Variable: file_magic_glob |
| How to find potential files when `deplibs_check_method' is |
| `file_magic'. `file_magic_glob' is a `sed' expression, and the |
| `sed' instance is fed potential file names that are transformed by |
| the `file_magic_glob' expression. Useful when the shell does not |
| support the shell option `nocaseglob', making `want_nocaseglob' |
| inappropriate. Normally disabled (i.e. `file_magic_glob' is |
| empty). |
| |
| -- Variable: finish_cmds |
| Commands to tell the dynamic linker how to find shared libraries |
| in a specific directory. |
| |
| -- Variable: finish_eval |
| Same as `finish_cmds', except the commands are not displayed. |
| |
| -- Variable: global_symbol_pipe |
| A pipeline that takes the output of `NM', and produces a listing of |
| raw symbols followed by their C names. For example: |
| |
| $ eval "$NM progname | $global_symbol_pipe" |
| D SYMBOL1 C-SYMBOL1 |
| T SYMBOL2 C-SYMBOL2 |
| C SYMBOL3 C-SYMBOL3 |
| ... |
| $ |
| |
| The first column contains the symbol type (used to tell data from |
| code) but its meaning is system dependent. |
| |
| -- Variable: global_symbol_to_cdecl |
| A pipeline that translates the output of `global_symbol_pipe' into |
| proper C declarations. Since some platforms, such as HP/UX, have |
| linkers that differentiate code from data, data symbols are |
| declared as data, and code symbols are declared as functions. |
| |
| -- Variable: hardcode_action |
| Either `immediate' or `relink', depending on whether shared |
| library paths can be hardcoded into executables before they are |
| installed, or if they need to be relinked. |
| |
| -- Variable: hardcode_direct |
| Set to `yes' or `no', depending on whether the linker hardcodes |
| directories if a library is directly specified on the command line |
| (such as `DIR/libNAME.a') when `hardcode_libdir_flag_spec' is |
| specified. |
| |
| -- Variable: hardcode_direct_absolute |
| Some architectures hardcode "absolute" library directories that |
| can not be overridden by `shlibpath_var' when `hardcode_direct' is |
| `yes'. In that case set `hardcode_direct_absolute' to `yes', or |
| otherwise `no'. |
| |
| -- Variable: hardcode_into_libs |
| Whether the platform supports hardcoding of run-paths into |
| libraries. If enabled, linking of programs will be much simpler |
| but libraries will need to be relinked during installation. Set |
| to `yes' or `no'. |
| |
| -- Variable: hardcode_libdir_flag_spec |
| Flag to hardcode a `libdir' variable into a binary, so that the |
| dynamic linker searches `libdir' for shared libraries at runtime. |
| If it is empty, libtool will try to use some other hardcoding |
| mechanism. |
| |
| -- Variable: hardcode_libdir_separator |
| If the compiler only accepts a single `hardcode_libdir_flag', then |
| this variable contains the string that should separate multiple |
| arguments to that flag. |
| |
| -- Variable: hardcode_minus_L |
| Set to `yes' or `no', depending on whether the linker hardcodes |
| directories specified by `-L' flags into the resulting executable |
| when `hardcode_libdir_flag_spec' is specified. |
| |
| -- Variable: hardcode_shlibpath_var |
| Set to `yes' or `no', depending on whether the linker hardcodes |
| directories by writing the contents of `$shlibpath_var' into the |
| resulting executable when `hardcode_libdir_flag_spec' is |
| specified. Set to `unsupported' if directories specified by |
| `$shlibpath_var' are searched at run time, but not at link time. |
| |
| -- Variable: host |
| -- Variable: host_alias |
| -- Variable: host_os |
| Set to the specified and canonical names of the system that |
| libtool was configured for. |
| |
| -- Variable: include_expsyms |
| List of symbols that must always be exported when using |
| `export_symbols'. |
| |
| -- Variable: inherit_rpath |
| Whether the linker adds runtime paths of dependency libraries to |
| the runtime path list, requiring libtool to relink the output when |
| installing. Set to `yes' or `no'. Default is `no'. |
| |
| -- Variable: install_override_mode |
| Permission mode override for installation of shared libraries. If |
| the runtime linker fails to load libraries with wrong permissions, |
| then it may fail to execute programs that are needed during |
| installation, because these need the library that has just been |
| installed. In this case, it is necessary to pass the mode to |
| `install' with `-m INSTALL_OVERRIDE_MODE'. |
| |
| -- Variable: libext |
| The standard old archive suffix (normally `a'). |
| |
| -- Variable: libname_spec |
| The format of a library name prefix. On all Unix systems, static |
| libraries are called `libNAME.a', but on some systems (such as |
| OS/2 or MS-DOS), the library is just called `NAME.a'. |
| |
| -- Variable: library_names_spec |
| A list of shared library names. The first is the name of the file, |
| the rest are symbolic links to the file. The name in the list is |
| the file name that the linker finds when given `-lNAME'. |
| |
| -- Variable: link_all_deplibs |
| Whether libtool must link a program against all its dependency |
| libraries. Set to `yes' or `no'. Default is `unknown', which is |
| a synonym for `yes'. |
| |
| -- Variable: link_static_flag |
| Linker flag (passed through the C compiler) used to prevent dynamic |
| linking. |
| |
| -- Variable: macro_version |
| -- Variable: macro_revision |
| The release and revision from which the libtool.m4 macros were |
| taken. This is used to ensure that macros and `ltmain.sh' |
| correspond to the same Libtool version. |
| |
| -- Variable: max_cmd_len |
| The approximate longest command line that can be passed to `$SHELL' |
| without being truncated, as computed by `LT_CMD_MAX_LEN'. |
| |
| -- Variable: need_lib_prefix |
| Whether we can `dlopen' modules without a `lib' prefix. Set to |
| `yes' or `no'. By default, it is `unknown', which means the same |
| as `yes', but documents that we are not really sure about it. |
| `no' means that it is possible to `dlopen' a module without the |
| `lib' prefix. |
| |
| -- Variable: need_version |
| Whether versioning is required for libraries, i.e. whether the |
| dynamic linker requires a version suffix for all libraries. Set |
| to `yes' or `no'. By default, it is `unknown', which means the |
| same as `yes', but documents that we are not really sure about it. |
| |
| -- Variable: need_locks |
| Whether files must be locked to prevent conflicts when compiling |
| simultaneously. Set to `yes' or `no'. |
| |
| -- Variable: nm_file_list_spec |
| Specify filename containing input files for `NM'. |
| |
| -- Variable: no_builtin_flag |
| Compiler flag to disable builtin functions that conflict with |
| declaring external global symbols as `char'. |
| |
| -- Variable: no_undefined_flag |
| The flag that is used by `archive_cmds' in order to declare that |
| there will be no unresolved symbols in the resulting shared |
| library. Empty, if no such flag is required. |
| |
| -- Variable: objdir |
| The name of the directory that contains temporary libtool files. |
| |
| -- Variable: objext |
| The standard object file suffix (normally `o'). |
| |
| -- Variable: pic_flag |
| Any additional compiler flags for building library object files. |
| |
| -- Variable: postinstall_cmds |
| -- Variable: old_postinstall_cmds |
| Commands run after installing a shared or static library, |
| respectively. |
| |
| -- Variable: postuninstall_cmds |
| -- Variable: old_postuninstall_cmds |
| Commands run after uninstalling a shared or static library, |
| respectively. |
| |
| -- Variable: postlink_cmds |
| Commands necessary for finishing linking programs. `postlink_cmds' |
| are executed immediately after the program is linked. Any |
| occurrence of the string `@OUTPUT@' in `postlink_cmds' is replaced |
| by the name of the created executable (i.e. not the wrapper, if a |
| wrapper is generated) prior to execution. Similarly, |
| `@TOOL_OUTPUT@' is replaced by the toolchain format of `@OUTPUT@'. |
| Normally disabled (i.e. `postlink_cmds' empty). |
| |
| -- Variable: reload_cmds |
| -- Variable: reload_flag |
| Commands to create a reloadable object. Set `reload_cmds' to |
| `false' on systems that cannot create reloadable objects. |
| |
| -- Variable: runpath_var |
| The environment variable that tells the linker which directories to |
| hardcode in the resulting executable. |
| |
| -- Variable: shlibpath_overrides_runpath |
| Indicates whether it is possible to override the hard-coded library |
| search path of a program with an environment variable. If this is |
| set to no, libtool may have to create two copies of a program in |
| the build tree, one to be installed and one to be run in the build |
| tree only. When each of these copies is created depends on the |
| value of `fast_install'. The default value is `unknown', which is |
| equivalent to `no'. |
| |
| -- Variable: shlibpath_var |
| The environment variable that tells the dynamic linker where to |
| find shared libraries. |
| |
| -- Variable: soname_spec |
| The name coded into shared libraries, if different from the real |
| name of the file. |
| |
| -- Variable: striplib |
| -- Variable: old_striplib |
| Command to strip a shared (`striplib') or static (`old_striplib') |
| library, respectively. If these variables are empty, the strip |
| flag in the install mode will be ignored for libraries (*note |
| Install mode::). |
| |
| -- Variable: sys_lib_dlsearch_path_spec |
| Expression to get the run-time system library search path. |
| Directories that appear in this list are never hard-coded into |
| executables. |
| |
| -- Variable: sys_lib_search_path_spec |
| Expression to get the compile-time system library search path. |
| This variable is used by libtool when it has to test whether a |
| certain library is shared or static. The directories listed in |
| `shlibpath_var' are automatically appended to this list, every time |
| libtool runs (i.e., not at configuration time), because some |
| linkers use this variable to extend the library search path. |
| Linker switches such as `-L' also augment the search path. |
| |
| -- Variable: thread_safe_flag_spec |
| Linker flag (passed through the C compiler) used to generate |
| thread-safe libraries. |
| |
| -- Variable: to_host_file_cmd |
| If the toolchain is not native to the build platform (e.g. if you |
| are using MSYS to drive the scripting, but are using the MinGW |
| native Windows compiler) this variable describes how to convert |
| file names from the format used by the build platform to the |
| format used by host platform. Normally set to |
| `func_convert_file_noop', libtool will autodetect most cases in |
| which other values should be used. On rare occasions, it may be |
| necessary to override the autodetected value (*note Cygwin to |
| MinGW Cross::). |
| |
| -- Variable: to_tool_file_cmd |
| If the toolchain is not native to the build platform (e.g. if you |
| are using some Unix to drive the scripting together with a Windows |
| toolchain running in Wine) this variable describes how to convert |
| file names from the format used by the build platform to the |
| format used by the toolchain. Normally set to |
| `func_convert_file_noop'. |
| |
| -- Variable: version_type |
| The library version numbering type. One of `libtool', |
| `freebsd-aout', `freebsd-elf', `irix', `linux', `osf', `sunos', |
| `windows', or `none'. |
| |
| -- Variable: want_nocaseglob |
| Find potential files using the shell option `nocaseglob', when |
| `deplibs_check_method' is `file_magic'. Normally set to `no'. Set |
| to `yes' to enable the `nocaseglob' shell option when looking for |
| potential file names in a case-insensitive manner. |
| |
| -- Variable: whole_archive_flag_spec |
| Compiler flag to generate shared objects from convenience archives. |
| |
| -- Variable: wl |
| The C compiler flag that allows libtool to pass a flag directly to |
| the linker. Used as: `${wl}SOME-FLAG'. |
| |
| Variables ending in `_cmds' or `_eval' contain a `~'-separated list |
| of commands that are `eval'ed one after another. If any of the |
| commands return a nonzero exit status, libtool generally exits with an |
| error message. |
| |
| Variables ending in `_spec' are `eval'ed before being used by |
| libtool. |
| |
| |
| File: libtool.info, Node: Cheap tricks, Prev: libtool script contents, Up: Maintaining |
| |
| 15.5 Cheap tricks |
| ================= |
| |
| Here are a few tricks that you can use in order to make maintainership |
| easier: |
| |
| * When people report bugs, ask them to use the `--config', |
| `--debug', or `--features' flags, if you think they will help you. |
| These flags are there to help you get information directly, rather |
| than having to trust second-hand observation. |
| |
| * Rather than reconfiguring libtool every time I make a change to |
| `ltmain.in', I keep a permanent `libtool' script in my `PATH', |
| which sources `ltmain.in' directly. |
| |
| The following steps describe how to create such a script, where |
| `/home/src/libtool' is the directory containing the libtool source |
| tree, `/home/src/libtool/libtool' is a libtool script that has been |
| configured for your platform, and `~/bin' is a directory in your |
| `PATH': |
| |
| trick$ cd ~/bin |
| trick$ sed 's%^\(macro_version=\).*$%\1@VERSION@%; |
| s%^\(macro_revision=\).*$%\1@package_revision@%; |
| /^# ltmain\.sh/q' /home/src/libtool/libtool > libtool |
| trick$ echo '. /home/src/libtool/ltmain.in' >> libtool |
| trick$ chmod +x libtool |
| trick$ libtool --version |
| ltmain.sh (GNU @PACKAGE@@TIMESTAMP@) @VERSION@ |
| |
| Copyright (C) 2011 Free Software Foundation, Inc. |
| This is free software; see the source for copying conditions. There is NO |
| warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. |
| trick$ |
| |
| The output of the final `libtool --version' command shows that the |
| `ltmain.in' script is being used directly. Now, modify `~/bin/libtool' |
| or `/home/src/libtool/ltmain.in' directly in order to test new changes |
| without having to rerun `configure'. |
| |