mirror of
git://git.savannah.gnu.org/libtool.git
synced 2024-12-03 06:30:13 +08:00
2235e08e8a
amount of tidying up to compensate.
4452 lines
163 KiB
Plaintext
4452 lines
163 KiB
Plaintext
\input texinfo @c -*-texinfo-*-
|
|
@c %**start of header
|
|
@setfilename libtool.info
|
|
@settitle Libtool
|
|
@c For double-sided printing, uncomment:
|
|
@c @setchapternewpage odd
|
|
@c %**end of header
|
|
|
|
@include version.texi
|
|
@set BUGADDR the libtool bug reporting address @email{bug-libtool@@gnu.org}
|
|
@set MAILLIST the libtool mailing list @email{libtool@@gnu.org}
|
|
@set objdir .libs
|
|
|
|
@dircategory GNU programming tools
|
|
@direntry
|
|
* Libtool: (libtool). Generic shared library support script.
|
|
@end direntry
|
|
|
|
@dircategory Individual utilities
|
|
@direntry
|
|
* libtoolize: (libtool)Invoking libtoolize. Adding libtool support.
|
|
@end direntry
|
|
|
|
@ifinfo
|
|
This file documents GNU Libtool @value{VERSION}
|
|
|
|
Copyright (C) 1996-2000 Free Software Foundation, Inc.
|
|
|
|
Permission is granted to make and distribute verbatim copies of this
|
|
manual provided the copyright notice and this permission notice are
|
|
preserved on all copies.
|
|
|
|
@ignore
|
|
Permission is granted to process this file through TeX and print the
|
|
results, provided the printed document carries copying permission notice
|
|
identical to this one except for the removal of this paragraph
|
|
|
|
|
|
@end ignore
|
|
Permission is granted to copy and distribute modified versions of this
|
|
manual under the conditions for verbatim copying, provided that the
|
|
entire resulting derived work is distributed under the terms of a
|
|
permission notice identical to this one.
|
|
|
|
Permission is granted to copy and distribute translations of this manual
|
|
into another language, under the above conditions for modified versions,
|
|
except that this permission notice may be stated in a translation
|
|
approved by the Foundation.
|
|
@end ifinfo
|
|
|
|
|
|
@titlepage
|
|
@title GNU Libtool
|
|
@subtitle For version @value{VERSION}, @value{UPDATED}
|
|
@author Gordon Matzigkeit
|
|
@author Alexandre Oliva
|
|
@author Thomas Tanner
|
|
@author Gary V. Vaughan
|
|
|
|
@page
|
|
@vskip 0pt plus 1filll
|
|
Copyright @copyright{} 1996-2000 Free Software Foundation, Inc.
|
|
|
|
Permission is granted to make and distribute verbatim copies of this
|
|
manual provided the copyright notice and this permission notice are
|
|
preserved on all copies.
|
|
|
|
Permission is granted to copy and distribute modified versions of this
|
|
manual under the conditions for verbatim copying, provided that the
|
|
entire resulting derived work is distributed under the terms of a
|
|
permission notice identical to this one.
|
|
|
|
Permission is granted to copy and distribute translations of this manual
|
|
into another language, under the above conditions for modified versions,
|
|
except that this permission notice may be stated in a translation
|
|
approved by the Free Software Foundation.
|
|
@end titlepage
|
|
|
|
@c Put everything in one index (arbitrarily chosen to be the concept index).
|
|
@syncodeindex vr cp
|
|
@syncodeindex fn cp
|
|
@syncodeindex tp cp
|
|
@synindex pg cp
|
|
|
|
@ifinfo
|
|
@node Top, Introduction, (dir), (dir)
|
|
@comment node-name, next, previous, up
|
|
@top 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 @value{VERSION}.
|
|
|
|
@xref{Reporting bugs}, for information on how to report problems with
|
|
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 @code{libtool} script.
|
|
* Integrating libtool:: Using libtool in your own packages.
|
|
* Versioning:: Using library interface versions.
|
|
* Library tips:: Tips for library interface design.
|
|
* Inter-library dependencies:: Libraries that depend on other libraries.
|
|
* Dlopened modules:: @code{dlopen}ing libtool-created libraries.
|
|
* Using libltdl:: Libtool's portable @code{dlopen} wrapper library.
|
|
* Other languages:: Using libtool without a C compiler.
|
|
* Troubleshooting:: When libtool doesn't work as advertised.
|
|
* Maintaining:: Information used by the libtool maintainer.
|
|
* Index:: Full index.
|
|
|
|
@detailmenu --- 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.
|
|
|
|
Invoking @code{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
|
|
|
|
* Makefile rules:: Writing @file{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
|
|
|
|
* AC_PROG_LIBTOOL:: Configuring @code{libtool} in @file{configure.in}.
|
|
|
|
Including libtool in your package
|
|
|
|
* Invoking libtoolize:: @code{libtoolize} command line options.
|
|
* Autoconf .o macros:: Autoconf macros that set object file names.
|
|
|
|
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.
|
|
* Finding the dlname:: Choosing the right file to @code{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 @code{dlopen}ed.
|
|
* Distributing libltdl:: How to distribute libltdl with your package.
|
|
* Module loaders for libltdl:: Creating user defined module loaders.
|
|
|
|
Using libtool with other languages
|
|
|
|
* C++ libraries::
|
|
|
|
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 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.
|
|
* Archivers:: Programs that create static archives.
|
|
|
|
@end detailmenu
|
|
@end menu
|
|
|
|
@end ifinfo
|
|
|
|
@node Introduction
|
|
@chapter Introduction
|
|
|
|
In the past, if a source code package developer wanted to take advantage
|
|
of the power of shared libraries, he needed to write custom support code
|
|
for each platform on which his package ran. He also had to design a
|
|
configuration interface so that the package installer could choose what sort of
|
|
libraries were built.
|
|
|
|
GNU Libtool simplifies the developer's 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@dots{} users don't need
|
|
to read obscure documentation in order to have their favorite source
|
|
package build shared libraries. They just run your package
|
|
@code{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, @file{libhello}, in a
|
|
generic way.
|
|
|
|
@file{libhello} could be a shared library, a static library, or
|
|
both@dots{} 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.
|
|
@end menu
|
|
|
|
@node Motivation
|
|
@section Motivation for writing libtool
|
|
|
|
@cindex motivation for writing libtool
|
|
@cindex design philosophy
|
|
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.
|
|
|
|
@cindex specifications for libtool
|
|
@cindex libtool specifications
|
|
The following specifications were used in developing and evaluating this
|
|
system:
|
|
|
|
@enumerate
|
|
@item
|
|
The system must be as elegant as possible.
|
|
|
|
@item
|
|
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.
|
|
|
|
@item
|
|
Portability to other (non-GNU) architectures and tools is desirable.
|
|
@end enumerate
|
|
|
|
@node Issues
|
|
@section Implementation issues
|
|
|
|
@cindex tricky design issues
|
|
@cindex design issues
|
|
The following issues need to be addressed in any reusable shared library
|
|
system, specifically libtool:
|
|
|
|
@enumerate
|
|
@item
|
|
The package installer should be able to control what sort of libraries
|
|
are built.
|
|
|
|
@item
|
|
It can be tricky to run dynamically linked programs whose libraries have
|
|
not yet been installed. @code{LD_LIBRARY_PATH} must be set properly (if
|
|
it is supported), or programs fail to run.
|
|
|
|
@item
|
|
The system must operate consistently even on hosts which don't support
|
|
shared libraries.
|
|
|
|
@item
|
|
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.
|
|
|
|
@item
|
|
It is not always obvious with which suffix a shared library should be
|
|
installed. This makes it difficult for @file{Makefile} rules, since they
|
|
generally assume that file names are the same from host to host.
|
|
|
|
@item
|
|
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.
|
|
|
|
@item
|
|
The install @file{Makefile} target should warn the package installer to set
|
|
the proper environment variables (@code{LD_LIBRARY_PATH} or equivalent),
|
|
or run @code{ldconfig}.
|
|
@end enumerate
|
|
|
|
@node Other implementations
|
|
@section 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.
|
|
|
|
@node Postmortem
|
|
@section A postmortem analysis of other implementations
|
|
|
|
@cindex other implementations, flaws in
|
|
@cindex reusability of library systems
|
|
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.
|
|
|
|
@cindex complexity of library systems
|
|
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 which were examined seemed
|
|
to be confident enough to settle on a single paradigm that just
|
|
@emph{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 @file{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.
|
|
|
|
@node Libtool paradigm
|
|
@chapter 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.
|
|
|
|
@cindex definition of libraries
|
|
@cindex libraries, definition of
|
|
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.
|
|
|
|
@node Using libtool
|
|
@chapter Using libtool
|
|
|
|
@cindex examples of using libtool
|
|
@cindex libtool examples
|
|
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:
|
|
|
|
@table @samp
|
|
@item a23
|
|
An Ultrix 4.2 platform with only static libraries.
|
|
|
|
@item burger
|
|
A NetBSD/i386 1.2 platform with shared libraries.
|
|
@end table
|
|
|
|
You can follow these examples on your own platform, using the
|
|
preconfigured libtool script that was installed with libtool
|
|
(@pxref{Configuring}).
|
|
|
|
Source files for the following examples are taken from the @file{demo}
|
|
subdirectory of the libtool distribution. Assume that we are building a
|
|
library, @file{libhello}, out of the files @file{foo.c} and
|
|
@file{hello.c}.
|
|
|
|
Note that the @file{foo.c} source file uses the @code{cos} math library
|
|
function, which is usually found in the standalone math library, and not
|
|
the C library (@pxref{Trig Functions, , Trigonometric Functions, libc,
|
|
The GNU C Library Reference Manual}). So, we need to add @kbd{-lm} to
|
|
the end of the link line whenever we link @file{foo.o} or @file{foo.lo}
|
|
into an executable or a library (@pxref{Inter-library dependencies}).
|
|
|
|
The same rule applies whenever you use functions that don't appear in
|
|
the standard C library@dots{} you need to add the appropriate
|
|
@kbd{-l@var{name}} 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
|
|
@file{main.o} against @file{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.
|
|
@end menu
|
|
|
|
@node Creating object files
|
|
@section Creating object files
|
|
|
|
@cindex compiling object files
|
|
@cindex object files, compiling
|
|
To create an object file from a source file, the compiler is invoked
|
|
with the `-c' flag (and any other desired flags):
|
|
|
|
@example
|
|
burger$ @kbd{gcc -g -O -c main.c}
|
|
burger$
|
|
@end example
|
|
|
|
The above compiler command produces an object file, @file{main.o}, from
|
|
the source file @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:
|
|
|
|
@example
|
|
burger$ @kbd{gcc -g -O -c foo.c}
|
|
burger$ @kbd{gcc -g -O -c hello.c}
|
|
burger$
|
|
@end example
|
|
|
|
@cindex position-independent code
|
|
@cindex PIC (position-independent code)
|
|
Shared libraries, however, may only be built from
|
|
@dfn{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.
|
|
|
|
@cindex library object file
|
|
@cindex @samp{.lo} files
|
|
@cindex object files, library
|
|
Since this is a library implementation detail, libtool hides the
|
|
complexity of PIC compiler flags by using separate library object files
|
|
(which end in @samp{.lo} instead of @samp{.o}). On systems without shared
|
|
libraries (or without special PIC compiler flags), these library object
|
|
files are identical to ``standard'' object files.
|
|
|
|
To create library object files for @file{foo.c} and @file{hello.c},
|
|
simply invoke libtool with the standard compilation command as
|
|
arguments (@pxref{Compile mode}):
|
|
|
|
@example
|
|
a23$ @kbd{libtool gcc -g -O -c foo.c}
|
|
gcc -g -O -c foo.c
|
|
echo timestamp > foo.lo
|
|
a23$ @kbd{libtool gcc -g -O -c hello.c}
|
|
gcc -g -O -c hello.c
|
|
echo timestamp > hello.lo
|
|
a23$
|
|
@end example
|
|
|
|
Note that libtool creates two files for each invocation. The @samp{.lo}
|
|
file is a library object, which may be built into a shared library, and
|
|
the @samp{.o} file is a standard object file. On @samp{a23}, the
|
|
library objects are just timestamps, because only static libraries are
|
|
supported.
|
|
|
|
On shared library systems, libtool automatically inserts the PIC
|
|
generation flags into the compilation command, so that the library
|
|
object and the standard object differ:
|
|
|
|
@example
|
|
burger$ @kbd{libtool gcc -g -O -c foo.c}
|
|
gcc -g -O -c -fPIC -DPIC foo.c
|
|
mv -f foo.o foo.lo
|
|
gcc -g -O -c foo.c >/dev/null 2>&1
|
|
burger$ @kbd{libtool gcc -g -O -c hello.c}
|
|
gcc -g -O -c -fPIC -DPIC hello.c
|
|
mv -f hello.o hello.lo
|
|
gcc -g -O -c hello.c >/dev/null 2>&1
|
|
burger$
|
|
@end example
|
|
|
|
Notice that the second run of GCC has its output discarded. This is
|
|
done so that compiler warnings aren't annoyingly duplicated.
|
|
|
|
@node Linking libraries
|
|
@section Linking libraries
|
|
|
|
@pindex ar
|
|
Without libtool, the programmer would invoke the @code{ar} command to
|
|
create a static library:
|
|
|
|
@example
|
|
burger$ @kbd{ar cru libhello.a hello.o foo.o}
|
|
burger$
|
|
@end example
|
|
|
|
@pindex ranlib
|
|
But of course, that would be too simple, so many systems require that
|
|
you run the @code{ranlib} command on the resulting library (to give it
|
|
better karma, or something):
|
|
|
|
@example
|
|
burger$ @kbd{ranlib libhello.a}
|
|
burger$
|
|
@end example
|
|
|
|
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
|
|
@code{ar} (and possibly @code{ranlib}) commands.
|
|
|
|
@cindex libtool libraries
|
|
@cindex @samp{.la} files
|
|
Again, the libtool library name differs from the standard name (it has a
|
|
@samp{.la} suffix instead of a @samp{.a} suffix). The arguments to libtool are
|
|
the same ones you would use to produce an executable named
|
|
@file{libhello.la} with your compiler (@pxref{Link mode}):
|
|
|
|
@example
|
|
a23$ @kbd{libtool gcc -g -O -o libhello.la foo.o hello.o}
|
|
libtool: cannot build libtool library `libhello.la' from non-libtool \
|
|
objects
|
|
a23$
|
|
@end example
|
|
|
|
Aha! Libtool caught a common error@dots{} trying to build a library
|
|
from standard objects instead of library objects. This doesn't matter
|
|
for static libraries, but on shared library systems, it is of great
|
|
importance.
|
|
|
|
So, let's try again, this time with the library object files. Remember
|
|
also that we need to add @kbd{-lm} to the link command line because
|
|
@file{foo.c} uses the @code{cos} math library function (@pxref{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, @file{/usr/local/lib})@footnote{If you don't
|
|
specify an @code{rpath}, then libtool builds a libtool convenience
|
|
archive, not a shared library (@pxref{Static libraries}).}:
|
|
|
|
@example
|
|
a23$ @kbd{libtool gcc -g -O -o libhello.la foo.lo hello.lo \
|
|
-rpath /usr/local/lib -lm}
|
|
mkdir @value{objdir}
|
|
ar cru @value{objdir}/libhello.a foo.o hello.o
|
|
ranlib @value{objdir}/libhello.a
|
|
creating libhello.la
|
|
a23$
|
|
@end example
|
|
|
|
Now, let's try the same trick on the shared library platform:
|
|
|
|
@example
|
|
burger$ @kbd{libtool gcc -g -O -o libhello.la foo.lo hello.lo \
|
|
-rpath /usr/local/lib -lm}
|
|
mkdir @value{objdir}
|
|
ld -Bshareable -o @value{objdir}/libhello.so.0.0 foo.lo hello.lo -lm
|
|
ar cru @value{objdir}/libhello.a foo.o hello.o
|
|
ranlib @value{objdir}/libhello.a
|
|
creating libhello.la
|
|
burger$
|
|
@end example
|
|
|
|
Now that's significantly cooler@dots{} libtool just ran an obscure
|
|
@code{ld} command to create a shared library, as well as the static
|
|
library.
|
|
|
|
@cindex @file{@value{objdir}} subdirectory
|
|
Note how libtool creates extra files in the @file{@value{objdir}}
|
|
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.
|
|
|
|
@node Linking executables
|
|
@section Linking executables
|
|
|
|
@cindex linking against installed libraries
|
|
If you choose at this point to @dfn{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
|
|
@samp{-L} and @samp{-l} flags to specify the library's location.
|
|
|
|
@cindex buggy system linkers
|
|
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.
|
|
|
|
@cindex security problems with buggy linkers
|
|
@cindex bugs, subtle ones caused by buggy linkers
|
|
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.
|
|
|
|
@cindex linking against uninstalled libraries
|
|
Here's the old way of linking against an uninstalled library:
|
|
|
|
@example
|
|
burger$ @kbd{gcc -g -O -o hell.old main.o libhello.a -lm}
|
|
burger$
|
|
@end example
|
|
|
|
Libtool's way is almost the same@footnote{However, you should avoid using
|
|
@samp{-L} or @samp{-l} flags to link against an uninstalled libtool
|
|
library. Just specify the relative path to the @samp{.la} file, such as
|
|
@file{../intl/libintl.la}. This is a design decision to eliminate any
|
|
ambiguity when linking against uninstalled shared libraries.}
|
|
(@pxref{Link mode}):
|
|
|
|
@example
|
|
a23$ @kbd{libtool gcc -g -O -o hell main.o libhello.la -lm}
|
|
gcc -g -O -o hell main.o ./@value{objdir}/libhello.a -lm
|
|
a23$
|
|
@end example
|
|
|
|
That looks too simple to be true. All libtool did was transform
|
|
@file{libhello.la} to @file{./@value{objdir}/libhello.a}, but remember
|
|
that @samp{a23} has no shared libraries.
|
|
|
|
On @samp{burger} the situation is different:
|
|
|
|
@example
|
|
burger$ @kbd{libtool gcc -g -O -o hell main.o libhello.la -lm}
|
|
gcc -g -O -o @value{objdir}/hell main.o -L./@value{objdir} -R/usr/local/lib -lhello -lm
|
|
creating hell
|
|
burger$
|
|
@end example
|
|
|
|
@cindex linking with installed libtool libraries
|
|
|
|
Now assume @file{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:
|
|
|
|
@example
|
|
burger$ @kbd{gcc -g -O -o test test.o -L/usr/local/lib -lhello}
|
|
@end example
|
|
|
|
However, unless @file{/usr/local/lib} is in the standard library search
|
|
path, you won't be able to run @code{test}. However, if you use libtool
|
|
to link the already-installed libtool library, it will do The Right
|
|
Thing (TM) for you:
|
|
|
|
@example
|
|
burger$ @kbd{libtool gcc -g -O -o test test.o /usr/local/lib/libhello.la}
|
|
gcc -g -O -o @value{objdir}/test test.o -Wl,--rpath
|
|
-Wl,/usr/local/lib /usr/local/lib/libhello.a -lm
|
|
creating test
|
|
burger$
|
|
@end example
|
|
|
|
Note that libtool added the necessary run-time path flag, as well as
|
|
@samp{-lm}, the library libhello.la depended upon. Nice, huh?
|
|
|
|
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. Libtool could probably be made smarter to avoid the
|
|
creation of the wrapper script in this case, but this is left as an
|
|
exercise for the reader.
|
|
|
|
|
|
@cindex wrapper scripts for programs
|
|
@cindex program wrapper scripts
|
|
Notice that the executable, @code{hell}, was actually created in the
|
|
@file{@value{objdir}} subdirectory. Then, a wrapper script was created
|
|
in the current directory.
|
|
|
|
On NetBSD 1.2, libtool encodes the installation directory of
|
|
@file{libhello}, by using the @samp{-R/usr/local/lib} compiler flag.
|
|
Then, the wrapper script guarantees that the executable finds the
|
|
correct shared library (the one in @file{./@value{objdir}}) until it is
|
|
properly installed.
|
|
|
|
Let's compare the two different programs:
|
|
|
|
@example
|
|
burger$ @kbd{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$ @kbd{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$
|
|
@end example
|
|
|
|
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?
|
|
|
|
@example
|
|
burger$ @kbd{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$ @kbd{ls -l @value{objdir}/hell @value{objdir}/libhello.*}
|
|
-rwxr-xr-x 1 gord gord 11647 Nov 14 12:10 @value{objdir}/hell
|
|
-rw-r--r-- 1 gord gord 4274 Nov 13 18:44 @value{objdir}/libhello.a
|
|
-rwxr-xr-x 1 gord gord 12205 Nov 13 18:44 @value{objdir}/libhello.so.0.0
|
|
burger$
|
|
@end example
|
|
|
|
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 @file{libhello} won't be an advantage
|
|
until we link it against at least a few more programs.
|
|
|
|
@node Debugging executables
|
|
@section Debugging executables
|
|
|
|
If @file{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:
|
|
|
|
@example
|
|
burger$ @kbd{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) @kbd{quit}
|
|
burger$
|
|
@end example
|
|
|
|
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:
|
|
|
|
@example
|
|
burger$ @kbd{gdb @value{objdir}/hell}
|
|
trick:/home/src/libtool/demo$ gdb .libs/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.
|
|
(gdb) @kbd{break main}
|
|
Breakpoint 1 at 0x8048547: file main.c, line 29.
|
|
(gdb) @kbd{run}
|
|
Starting program: /home/src/libtool/demo/.libs/hell
|
|
/home/src/libtool/demo/.libs/hell: can't load library 'libhello.so.2'
|
|
|
|
Program exited with code 020.
|
|
(gdb) @kbd{quit}
|
|
burger$
|
|
@end example
|
|
|
|
Argh. Now GDB complains because it cannot find the shared library that
|
|
@file{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 @file{@value{objdir}} directory, and just run it on
|
|
the executable wrapper (@pxref{Execute mode}):
|
|
|
|
@example
|
|
burger$ @kbd{libtool 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.
|
|
(gdb) @kbd{break main}
|
|
Breakpoint 1 at 0x8048547: file main.c, line 29.
|
|
(gdb) @kbd{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) @kbd{quit}
|
|
The program is running. Quit anyway (and kill it)? (y or n) @kbd{y}
|
|
burger$
|
|
@end example
|
|
|
|
@node Installing libraries
|
|
@section Installing libraries
|
|
|
|
@pindex strip
|
|
Installing libraries on a non-libtool system is quite
|
|
straightforward@dots{} just copy them into place:@footnote{Don't
|
|
accidentally strip the libraries, though, or they will be unusable.}
|
|
|
|
@pindex su
|
|
@example
|
|
burger$ @kbd{su}
|
|
Password: @kbd{********}
|
|
burger# @kbd{cp libhello.a /usr/local/lib/libhello.a}
|
|
burger#
|
|
@end example
|
|
|
|
Oops, don't forget the @code{ranlib} command:
|
|
|
|
@example
|
|
burger# @kbd{ranlib /usr/local/lib/libhello.a}
|
|
burger#
|
|
@end example
|
|
|
|
@pindex install
|
|
Libtool installation is quite simple, as well. Just use the
|
|
@code{install} or @code{cp} command that you normally would
|
|
(@pxref{Install mode}):
|
|
|
|
@example
|
|
a23# @kbd{libtool cp libhello.la /usr/local/lib/libhello.la}
|
|
cp libhello.la /usr/local/lib/libhello.la
|
|
cp @value{objdir}/libhello.a /usr/local/lib/libhello.a
|
|
ranlib /usr/local/lib/libhello.a
|
|
a23#
|
|
@end example
|
|
|
|
Note that the libtool library @file{libhello.la} is also installed, to
|
|
help libtool with uninstallation (@pxref{Uninstall mode}) and linking
|
|
(@pxref{Linking executables}) and to help programs with dlopening
|
|
(@pxref{Dlopened modules}).
|
|
|
|
Here is the shared library example:
|
|
|
|
@example
|
|
burger# @kbd{libtool install -c libhello.la /usr/local/lib/libhello.la}
|
|
install -c @value{objdir}/libhello.so.0.0 /usr/local/lib/libhello.so.0.0
|
|
install -c libhello.la /usr/local/lib/libhello.la
|
|
install -c @value{objdir}/libhello.a /usr/local/lib/libhello.a
|
|
ranlib /usr/local/lib/libhello.a
|
|
burger#
|
|
@end example
|
|
|
|
@cindex stripping libraries
|
|
@cindex libraries, stripping
|
|
It is safe to specify the @samp{-s} (strip symbols) flag if you use a
|
|
BSD-compatible install program when installing libraries.
|
|
Libtool will either ignore the @samp{-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
|
|
@samp{-rpath} flag you used to build it.
|
|
|
|
@cindex postinstallation
|
|
@cindex installation, finishing
|
|
@cindex libraries, finishing installation
|
|
Then, running @samp{libtool -n --finish @var{libdir}} can give you
|
|
further hints on what to do (@pxref{Finish mode}):
|
|
|
|
@example
|
|
burger# @kbd{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#
|
|
@end example
|
|
|
|
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.
|
|
|
|
@node Installing executables
|
|
@section Installing executables
|
|
|
|
If you used libtool to link any executables against uninstalled libtool
|
|
libraries (@pxref{Linking executables}), you need to use libtool to
|
|
install the executables after the libraries have been installed
|
|
(@pxref{Installing libraries}).
|
|
|
|
So, for our Ultrix example, we would run:
|
|
|
|
@example
|
|
a23# libtool install -c hell /usr/local/bin/hell
|
|
install -c hell /usr/local/bin/hell
|
|
a23#
|
|
@end example
|
|
|
|
On shared library systems, libtool just ignores the wrapper script and
|
|
installs the correct binary:
|
|
|
|
@example
|
|
burger# libtool install -c hell /usr/local/bin/hell
|
|
install -c @value{objdir}/hell /usr/local/bin/hell
|
|
burger#
|
|
@end example
|
|
|
|
@node Static libraries
|
|
@section Linking static libraries
|
|
|
|
@cindex static linking
|
|
@cindex convenience libraries
|
|
Why return to @code{ar} and @code{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
|
|
programs. You can create a ``convenience library'' out of those
|
|
objects, and link programs with the library, instead of listing all
|
|
object files for every program. This technique is often used to
|
|
overcome GNU automake's lack of support for linking object files built
|
|
from sources in other directories, because it supports linking with
|
|
libraries from other directories. This limitation applies to GNU
|
|
automake up to release 1.4; newer releases should support sources in
|
|
other directories.
|
|
|
|
If you just want to link this convenience library into programs, then
|
|
you could just ignore libtool entirely, and use the old @code{ar} and
|
|
@code{ranlib} commands (or the corresponding GNU automake
|
|
@samp{_LIBRARIES} rules). You can even install a convenience library
|
|
(but you probably don't want to) using libtool:
|
|
|
|
@example
|
|
burger$ @kbd{libtool ./install-sh -c libhello.a /local/lib/libhello.a}
|
|
./install-sh -c libhello.a /local/lib/libhello.a
|
|
ranlib /local/lib/libhello.a
|
|
burger$
|
|
@end example
|
|
|
|
Using libtool for static library installation protects your library from
|
|
being accidentally stripped (if the installer used the @samp{-s} flag),
|
|
as well as automatically running the correct @code{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 @samp{-rpath} flag and use @samp{-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 @samp{-rpath} and @samp{-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.
|
|
|
|
When GNU automake is used, you should use @code{noinst_LTLIBRARIES}
|
|
instead of @code{lib_LTLIBRARIES} for convenience libraries, so that
|
|
the @samp{-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.
|
|
|
|
@cindex standalone binaries
|
|
Another common situation where static linking is desirable is in
|
|
creating a standalone binary. Use libtool to do the linking and add the
|
|
@samp{-all-static} flag.
|
|
|
|
@node Invoking libtool
|
|
@chapter Invoking @code{libtool}
|
|
@pindex libtool
|
|
@cindex libtool command options
|
|
@cindex options, libtool command
|
|
@cindex command options, libtool
|
|
|
|
The @code{libtool} program has the following synopsis:
|
|
|
|
@example
|
|
libtool [@var{option}]@dots{} [@var{mode-arg}]@dots{}
|
|
@end example
|
|
|
|
@noindent
|
|
and accepts the following options:
|
|
|
|
@table @samp
|
|
@item --config
|
|
Display libtool configuration variables and exit.
|
|
|
|
@item --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 @code{less} (or
|
|
@code{more}) or redirect to a file.
|
|
|
|
@item -n
|
|
@itemx --dry-run
|
|
Don't create, modify, or delete any files, just show what commands would
|
|
be executed by libtool.
|
|
|
|
@item --features
|
|
Display basic configuration options. This provides a way for packages
|
|
to determine whether shared or static libraries will be built.
|
|
|
|
@item --finish
|
|
Same as @samp{--mode=finish}.
|
|
|
|
@item --help
|
|
Display a help message and exit. If @samp{--mode=@var{mode}} is
|
|
specified, then detailed help for @var{mode} is
|
|
displayed.
|
|
|
|
@item --mode=@var{mode}
|
|
Use @var{mode} as the operation mode. By default, the operation mode is
|
|
inferred from the @var{mode-args}.
|
|
|
|
If @var{mode} is specified, it must be one of the following:
|
|
|
|
@table @samp
|
|
@item compile
|
|
Compile a source file into a libtool object.
|
|
|
|
@item execute
|
|
Automatically set the library path so that another program can use
|
|
uninstalled libtool-generated programs or libraries.
|
|
|
|
@item finish
|
|
Complete the installation of libtool libraries on the system.
|
|
|
|
@item install
|
|
Install libraries or executables.
|
|
|
|
@item link
|
|
Create a library or an executable.
|
|
|
|
@item uninstall
|
|
Delete installed libraries or executables.
|
|
|
|
@item clean
|
|
Delete uninstalled libraries or executables.
|
|
@end table
|
|
|
|
@item --version
|
|
Print libtool version information and exit.
|
|
@end table
|
|
|
|
The @var{mode-args} are a variable number of arguments, depending on the
|
|
selected operation mode. In general, each @var{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.
|
|
@end menu
|
|
|
|
@node Compile mode
|
|
@section Compile mode
|
|
@cindex mode, compile
|
|
@cindex compile mode
|
|
|
|
For @dfn{compile} mode, @var{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 @samp{-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. @samp{.c} for C source code) with the library object suffix,
|
|
@samp{.lo}.
|
|
|
|
If shared libraries are being built, any necessary PIC generation flags
|
|
are substituted into the compilation command.
|
|
You can pass compiler and linker specific flags using @samp{-Wc,@var{flag}}
|
|
and @samp{-Xcompiler @var{flag}} or @samp{-Wl,@var{flag}} and
|
|
@samp{-Xlinker @var{flag}}, respectively.
|
|
|
|
If the @samp{-static} option is given, then a @samp{.o} file is built,
|
|
even if libtool was configured with @samp{--disable-static}.
|
|
|
|
Note that the @samp{-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
|
|
@example
|
|
libtool gcc -c foo/x.c -o foo/x.lo
|
|
@end example
|
|
will do what you expect.
|
|
|
|
Note, however, that, if the compiler does not support @samp{-c} and
|
|
@samp{-o}, it is impossible to compile @file{foo/x.c} without
|
|
overwriting an existing @file{./x.o}. Therefore, if you do have a
|
|
source file @file{./x.c}, make sure you introduce dependencies in your
|
|
@file{Makefile} to make sure @file{./x.o} (or @file{./x.lo}) is
|
|
re-created after any sub-directory's @file{x.lo}:
|
|
@example
|
|
x.o x.lo: foo/x.lo bar/x.lo
|
|
@end example
|
|
This will also ensure that make won't try to use a temporarily corrupted
|
|
@file{x.o} to create a program or library. It may cause needless
|
|
recompilation on platforms that support @samp{-c} and @samp{-o}
|
|
together, but it's the only way to make it safe for those that don't.
|
|
|
|
@node Link mode
|
|
@section Link mode
|
|
@cindex link mode
|
|
@cindex mode, link
|
|
|
|
@dfn{Link} mode links together object files (including library
|
|
objects) to form another library or to create an executable program.
|
|
|
|
@var{mode-args} consist of a command using the C compiler to create an
|
|
output file (with the @samp{-o} flag) from several object files.
|
|
|
|
The following components of @var{mode-args} are treated specially:
|
|
|
|
@table @samp
|
|
@cindex undefined symbols, allowing
|
|
@cindex unresolved symbols, allowing
|
|
@item -all-static
|
|
If @var{output-file} is a program, then do not link it against any
|
|
shared libraries at all. If @var{output-file} is a library, then only
|
|
create a static library.
|
|
|
|
@item -avoid-version
|
|
Tries to avoid versioning (@pxref{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.
|
|
|
|
@item -dlopen @var{file}
|
|
Same as @samp{-dlpreopen @var{file}}, if native dlopening is not
|
|
supported on the host platform (@pxref{Dlopened modules}) or if
|
|
the program is linked with @samp{-static} or @samp{-all-static}.
|
|
Otherwise, no effect. If @var{file} is @code{self} libtool will make
|
|
sure that the program can @code{dlopen} itself, either by enabling
|
|
@code{-export-dynamic} or by falling back to @samp{-dlpreopen self}.
|
|
|
|
@item -dlpreopen @var{file}
|
|
Link @var{file} into the output program, and add its symbols to
|
|
@var{lt_preloaded_symbols} (@pxref{Dlpreopening}). If @var{file} is
|
|
@code{self}, the symbols of the program itself will be added to
|
|
@var{lt_preloaded_symbols}.
|
|
If @var{file} is @code{force} libtool will make sure that
|
|
@var{lt_preloaded_symbols} is always @emph{defined}, regardless of whether
|
|
it's empty or not.
|
|
|
|
@item -export-dynamic
|
|
Allow symbols from @var{output-file} to be resolved with @code{dlsym}
|
|
(@pxref{Dlopened modules}).
|
|
|
|
@item -export-symbols @var{symfile}
|
|
Tells the linker to export only the symbols listed in @var{symfile}.
|
|
The symbol file should end in @samp{.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.
|
|
|
|
@item -export-symbols-regex @var{regex}
|
|
Same as @samp{-export-symbols}, except that only symbols matching
|
|
the regular expression @var{regex} are exported.
|
|
By default all symbols are exported.
|
|
|
|
@item -L@var{libdir}
|
|
Search @var{libdir} for required libraries that have already been
|
|
installed.
|
|
|
|
@item -l@var{name}
|
|
@var{output-file} requires the installed library @file{lib@var{name}}.
|
|
This option is required even when @var{output-file} is not an
|
|
executable.
|
|
|
|
@item -module
|
|
Creates a library that can be dlopened (@pxref{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.
|
|
|
|
@item -no-fast-install
|
|
Disable fast-install mode for the executable @var{output-file}. Useful
|
|
if the program won't be necessarily installed.
|
|
|
|
@item -no-install
|
|
Link an executable @var{output-file} that can't be installed and
|
|
therefore doesn't need a wrapper script. Useful if the program is only
|
|
used in the build tree, e.g., for testing or generating other files.
|
|
|
|
@item -no-undefined
|
|
Declare that @var{output-file} does not depend on any other libraries.
|
|
Some platforms cannot create shared libraries that depend on other
|
|
libraries (@pxref{Inter-library dependencies}).
|
|
|
|
@item -o @var{output-file}
|
|
Create @var{output-file} from the specified objects and libraries.
|
|
|
|
@item -release @var{release}
|
|
Specify that the library was generated by release @var{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 @samp{-version-info} flag instead (@pxref{Versioning}).
|
|
|
|
@item -rpath @var{libdir}
|
|
If @var{output-file} is a library, it will eventually be installed in
|
|
@var{libdir}. If @var{output-file} is a program, add @var{libdir} to
|
|
the run-time path of the program.
|
|
|
|
@item -R @var{libdir}
|
|
If @var{output-file} is a program, add @var{libdir} to its run-time
|
|
path. If @var{output-file} is a library, add -R@var{libdir} to its
|
|
@var{dependency_libs}, so that, whenever the library is linked into a
|
|
program, @var{libdir} will be added to its run-time path.
|
|
|
|
@item -static
|
|
If @var{output-file} is a program, then do not link it against any
|
|
uninstalled shared libtool libraries. If @var{output-file} is a
|
|
library, then only create a static library.
|
|
|
|
@item -version-info @var{current}[:@var{revision}[:@var{age}]]
|
|
If @var{output-file} is a libtool library, use interface version
|
|
information @var{current}, @var{revision}, and @var{age} to build it
|
|
(@pxref{Versioning}). Do @strong{not} use this flag to specify package
|
|
release information, rather see the @samp{-release} flag.
|
|
|
|
@item -Wl,@var{flag}
|
|
@itemx -Xlinker @var{flag}
|
|
Pass a linker specific flag directly to the linker.
|
|
@end table
|
|
|
|
If the @var{output-file} ends in @samp{.la}, then a libtool library is
|
|
created, which must be built only from library objects (@samp{.lo} files).
|
|
The @samp{-rpath} option is required. In the current implementation,
|
|
libtool libraries may not depend on other uninstalled libtool libraries
|
|
(@pxref{Inter-library dependencies}).
|
|
|
|
If the @var{output-file} ends in @samp{.a}, then a standard library is
|
|
created using @code{ar} and possibly @code{ranlib}.
|
|
|
|
@cindex partial linking
|
|
@cindex linking, partial
|
|
If @var{output-file} ends in @samp{.o} or @samp{.lo}, then a reloadable object
|
|
file is created from the input files (generally using @samp{ld -r}).
|
|
This method is often called @dfn{partial linking}.
|
|
|
|
Otherwise, an executable program is created.
|
|
|
|
@node Execute mode
|
|
@section Execute mode
|
|
@cindex execute mode
|
|
@cindex mode, execute
|
|
|
|
For @dfn{execute} mode, the library path is automatically set, then a
|
|
program is executed.
|
|
|
|
The first of the @var{mode-args} is treated as a program name, with the
|
|
rest as arguments to that program.
|
|
|
|
The following components of @var{mode-args} are treated specially:
|
|
|
|
@table @samp
|
|
@item -dlopen @var{file}
|
|
Add the directory containing @var{file} to the library path.
|
|
@end table
|
|
|
|
This mode sets the library path environment variable according to any
|
|
@samp{-dlopen} flags.
|
|
|
|
If any of the @var{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.
|
|
|
|
@node Install mode
|
|
@section Install mode
|
|
@cindex install mode
|
|
@cindex mode, install
|
|
|
|
In @dfn{install} mode, libtool interprets @var{mode-args} as an
|
|
installation command beginning with @code{cp}, or a BSD-compatible
|
|
@code{install} program.
|
|
|
|
The rest of the @var{mode-args} are interpreted as arguments to that
|
|
command.
|
|
|
|
The command is run, and any necessary unprivileged post-installation
|
|
commands are also completed.
|
|
|
|
@node Finish mode
|
|
@section Finish mode
|
|
@cindex finish mode
|
|
@cindex mode, finish
|
|
|
|
@dfn{Finish} mode helps system administrators install libtool libraries
|
|
so that they can be located and linked into user programs.
|
|
|
|
Each @var{mode-arg} is interpreted as the name of a library directory.
|
|
Running this command may require superuser privileges, so the
|
|
@samp{--dry-run} option may be useful.
|
|
|
|
@node Uninstall mode
|
|
@section Uninstall mode
|
|
@cindex uninstall mode
|
|
@cindex mode, uninstall
|
|
|
|
@dfn{Uninstall} mode deletes installed libraries, executables and objects.
|
|
|
|
The first @var{mode-arg} is the name of the program to use to delete
|
|
files (typically @file{/bin/rm}).
|
|
|
|
The remaining @var{mode-args} are either flags for the deletion program
|
|
(beginning with a `-'), or the names of files to delete.
|
|
|
|
@node Clean mode
|
|
@section Clean mode
|
|
@cindex clean mode
|
|
@cindex mode, clean
|
|
|
|
@dfn{Clean} mode deletes uninstalled libraries, executables, objects
|
|
and libtool's temporary files associated with them.
|
|
|
|
The first @var{mode-arg} is the name of the program to use to delete
|
|
files (typically @file{/bin/rm}).
|
|
|
|
The remaining @var{mode-args} are either flags for the deletion program
|
|
(beginning with a `-'), or the names of files to delete.
|
|
|
|
@node Integrating libtool
|
|
@chapter 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.
|
|
|
|
@menu
|
|
* Makefile rules:: Writing @file{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.
|
|
@end menu
|
|
|
|
@node Makefile rules
|
|
@section Writing @file{Makefile} rules for libtool
|
|
@cindex Makefile
|
|
@cindex Makefile.am
|
|
@cindex Makefile.in
|
|
|
|
Libtool is fully integrated with Automake (@pxref{Top,, Introduction,
|
|
automake, The Automake Manual}), starting with Automake version 1.2.
|
|
|
|
If you want to use libtool in a regular @file{Makefile} (or
|
|
@file{Makefile.in}), you are on your own. If you're not using Automake
|
|
1.2, and you don't know how to incorporate libtool into your package you
|
|
need to do one of the following:
|
|
|
|
@enumerate 1
|
|
@item
|
|
Download Automake (version 1.2 or later) from your nearest GNU mirror,
|
|
install it, and start using it.
|
|
|
|
@item
|
|
Learn how to write @file{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 @file{Makefile.in} in the @file{demo}
|
|
subdirectory of the libtool distribution@dots{} note especially that it
|
|
was automatically generated from the @file{Makefile.am} by Automake).
|
|
@end enumerate
|
|
|
|
@node Using Automake
|
|
@section Using Automake with libtool
|
|
|
|
@vindex LTLIBRARIES
|
|
Libtool library support is implemented under the @samp{LTLIBRARIES}
|
|
primary.
|
|
|
|
Here are some samples from the Automake @file{Makefile.am} in the
|
|
libtool distribution's @file{demo} subdirectory.
|
|
|
|
First, to link a program against a libtool library, just use the
|
|
@samp{program_LDADD} variable:
|
|
|
|
@example
|
|
bin_PROGRAMS = hell hell.debug
|
|
|
|
# Build hell from main.c and libhello.la
|
|
hell_SOURCES = main.c
|
|
hell_LDADD = libhello.la
|
|
|
|
# Create an easier-to-debug version of hell.
|
|
hell_debug_SOURCES = main.c
|
|
hell_debug_LDADD = libhello.la
|
|
hell_debug_LDFLAGS = -static
|
|
@end example
|
|
|
|
The flags @samp{-dlopen} or @samp{-dlpreopen} (@pxref{Link mode}) would
|
|
fit better in the @var{program_LDADD} variable. Unfortunately, GNU
|
|
automake, up to release 1.4, doesn't accept these flags in a
|
|
@var{program_LDADD} variable, so you have the following alternatives:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
add them to @var{program_LDFLAGS}, and list the libraries in
|
|
@var{program_DEPENDENCIES}, then wait for a release of GNU automake that
|
|
accepts these flags where they belong;
|
|
|
|
@item
|
|
surround the flags between quotes, but then you must set
|
|
@var{program_DEPENDENCIES} too:
|
|
|
|
@example
|
|
program_LDADD = "-dlopen" libfoo.la
|
|
program_DEPENDENCIES = libfoo.la
|
|
@end example
|
|
|
|
@item
|
|
set and @samp{AC_SUBST} variables @var{DLOPEN} and @var{DLPREOPEN} in
|
|
@file{configure.in} and use @samp{@@DLOPEN@@} and @samp{@@DLPREOPEN@@}
|
|
as replacements for the explicit flags @samp{-dlopen} and
|
|
@samp{-dlpreopen} in @samp{program_LDADD}. Automake will discard
|
|
@samp{AC_SUBST}ed variables from dependencies, so it will behave exactly
|
|
as we expect it to behave when it accepts these flags in
|
|
@samp{program_LDADD}. But hey!, this is ugly!
|
|
@end itemize
|
|
|
|
You may use the @samp{program_LDFLAGS} variable to stuff in any flags
|
|
you want to pass to libtool while linking @samp{program} (such as
|
|
@samp{-static} to avoid linking uninstalled shared libtool libraries).
|
|
|
|
Building a libtool library is almost as trivial@dots{} note the use of
|
|
@samp{libhello_la_LDFLAGS} to pass the @samp{-version-info}
|
|
(@pxref{Versioning}) option to libtool:
|
|
|
|
@example
|
|
# 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
|
|
@end example
|
|
|
|
The @samp{-rpath} option is passed automatically by Automake (except for
|
|
libraries listed as @code{noinst_LTLIBRARIES}), so you
|
|
should not specify it.
|
|
|
|
@xref{A Shared Library, Building a Shared Library, The Automake Manual,
|
|
automake, The Automake Manual}, for more information.
|
|
|
|
@node Configuring
|
|
@section Configuring libtool
|
|
@cindex 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
|
|
(@pxref{Distributing}), you do not always know which compiler suite and
|
|
operating system are used to compile your package.
|
|
|
|
For this reason, libtool must be @dfn{configured} before it can be
|
|
used. This idea should be familiar to anybody who has used a GNU
|
|
@code{configure} script. @code{configure} runs a number of tests for
|
|
system features, then generates the @file{Makefiles} (and possibly a
|
|
@file{config.h} header file), after which you can run @code{make} and
|
|
build the package.
|
|
|
|
Libtool adds its own tests to your @code{configure} script in order to
|
|
generate a libtool script for the installer's host machine.
|
|
|
|
@menu
|
|
* AC_PROG_LIBTOOL:: Configuring @code{libtool} in @file{configure.in}.
|
|
@end menu
|
|
|
|
@node AC_PROG_LIBTOOL
|
|
@subsection The @code{AC_PROG_LIBTOOL} macro
|
|
|
|
If you are using GNU Autoconf (or Automake), you should add a call to
|
|
@code{AC_PROG_LIBTOOL} to your @file{configure.in} file. This macro
|
|
adds many new tests to the @code{configure} script so that the generated
|
|
libtool script will understand the characteristics of the host:
|
|
|
|
@defmac AC_PROG_LIBTOOL
|
|
@defmacx AM_PROG_LIBTOOL
|
|
Add support for the @samp{--enable-shared} and @samp{--disable-shared}
|
|
@code{configure} flags.@footnote{@code{AC_PROG_LIBTOOL} requires that
|
|
you define the @file{Makefile} variable @code{top_builddir} in your
|
|
@file{Makefile.in}. Automake does this automatically, but Autoconf
|
|
users should set it to the relative path to the top of your build
|
|
directory (@file{../..}, for example).} @code{AM_PROG_LIBTOOL} was the
|
|
old name for this macro, and although supported at the moment is
|
|
deprecated.
|
|
|
|
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 calling either the
|
|
@code{AC_DISABLE_SHARED} or @code{AC_DISABLE_STATIC} macros:
|
|
|
|
@example
|
|
# Turn off shared libraries during beta-testing, since they
|
|
# make the build process take too long.
|
|
AC_DISABLE_SHARED
|
|
AC_PROG_LIBTOOL
|
|
@end example
|
|
|
|
The user may specify modified forms of the configure flags
|
|
@samp{--enable-shared} and @samp{--enable-static} to choose whether
|
|
shared or static libraries are built based on the name of the package.
|
|
For example, to have shared @samp{bfd} and @samp{gdb} libraries built,
|
|
but not shared @samp{libg++}, you can run all three @code{configure}
|
|
scripts as follows:
|
|
|
|
@example
|
|
trick$ ./configure --enable-shared=bfd,gdb
|
|
@end example
|
|
|
|
In general, specifying @samp{--enable-shared=@var{pkgs}} is the same as
|
|
configuring with @samp{--enable-shared} every package named in the
|
|
comma-separated @var{pkgs} list, and every other package with
|
|
@samp{--disable-shared}. The @samp{--enable-static=@var{pkgs}} flag
|
|
behaves similarly, but it uses @samp{--enable-static} and
|
|
@samp{--disable-static}. The same applies to the
|
|
@samp{--enable-fast-install=@var{pkgs}} flag, which uses
|
|
@samp{--enable-fast-install} and @samp{--disable-fast-install}.
|
|
|
|
The package name @samp{default} matches any packages which have not set
|
|
their name in the @code{PACKAGE} environment variable.
|
|
|
|
This macro also sets the shell variable @var{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 @file{configure.in}:
|
|
|
|
@example
|
|
AC_PROG_LIBTOOL
|
|
AC_SUBST(LIBTOOL_DEPS)
|
|
@end example
|
|
|
|
and, to @file{Makefile.in} or @file{Makefile.am}:
|
|
|
|
@example
|
|
LIBTOOL_DEPS = @@LIBTOOL_DEPS@@
|
|
libtool: $(LIBTOOL_DEPS)
|
|
$(SHELL) ./config.status --recheck
|
|
@end example
|
|
|
|
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 @file{libtool}.
|
|
|
|
@end defmac
|
|
|
|
@defmac AC_LIBTOOL_DLOPEN
|
|
Enable checking for dlopen support. This macro should be used if
|
|
the package makes use of the @samp{-dlopen} and @samp{-dlpreopen} flags,
|
|
otherwise libtool will assume that the system does not support dlopening.
|
|
The macro must be called @strong{before} @code{AC_PROG_LIBTOOL}.
|
|
@end defmac
|
|
|
|
@defmac AC_LIBTOOL_WIN32_DLL
|
|
This macro 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 @code{__declspec(dllexport)} and imported with
|
|
@code{__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.
|
|
|
|
This macro must be called @strong{before} @code{AC_PROG_LIBTOOL}, and
|
|
provision must be made to pass @samp{-no-undefined} to @code{libtool}
|
|
in link mode from the package @code{Makefile}. Naturally, if you pass
|
|
@samp{-no-undefined}, you must ensure that all the library symbols
|
|
@strong{really are} defined at link time!
|
|
@end defmac
|
|
|
|
@defmac AC_DISABLE_FAST_INSTALL
|
|
Change the default behaviour for @code{AC_PROG_LIBTOOL} to disable
|
|
optimization for fast installation. The user may still override this
|
|
default, depending on platform support, by specifying
|
|
@samp{--enable-fast-install}.
|
|
@end defmac
|
|
|
|
@defmac AC_DISABLE_SHARED
|
|
@defmacx AM_DISABLE_SHARED
|
|
Change the default behaviour for @code{AC_PROG_LIBTOOL} to disable
|
|
shared libraries. The user may still override this default by
|
|
specifying @samp{--enable-shared}.
|
|
@end defmac
|
|
|
|
@defmac AC_DISABLE_STATIC
|
|
@defmacx AM_DISABLE_STATIC
|
|
Change the default behaviour for @code{AC_PROG_LIBTOOL} to disable
|
|
static libraries. The user may still override this default by
|
|
specifying @samp{--enable-static}.
|
|
@end defmac
|
|
|
|
The tests in @code{AC_PROG_LIBTOOL} also recognize the following
|
|
environment variables:
|
|
|
|
@defvar CC
|
|
The C compiler that will be used by the generated @code{libtool}. If
|
|
this is not set, @code{AC_PROG_LIBTOOL} will look for @code{gcc} or
|
|
@code{cc}.
|
|
@end defvar
|
|
|
|
@defvar CFLAGS
|
|
Compiler flags used to generate standard object files. If this is not
|
|
set, @code{AC_PROG_LIBTOOL} will not use any such flags. It affects
|
|
only the way @code{AC_PROG_LIBTOOL} runs tests, not the produced
|
|
@code{libtool}.
|
|
@end defvar
|
|
|
|
@defvar CPPFLAGS
|
|
C preprocessor flags. If this is not set, @code{AC_PROG_LIBTOOL} will
|
|
not use any such flags. It affects only the way @code{AC_PROG_LIBTOOL}
|
|
runs tests, not the produced @code{libtool}.
|
|
@end defvar
|
|
|
|
@defvar LD
|
|
The system linker to use (if the generated @code{libtool} requires one).
|
|
If this is not set, @code{AC_PROG_LIBTOOL} will try to find out what is
|
|
the linker used by @var{CC}.
|
|
@end defvar
|
|
|
|
@defvar LDFLAGS
|
|
The flags to be used by @code{ltconfig} when it links a program. If
|
|
this is not set, @code{AC_PROG_LIBTOOL} will not use any such flags. It
|
|
affects only the way @code{AC_PROG_LIBTOOL} runs tests, not the produced
|
|
@code{libtool}.
|
|
@end defvar
|
|
|
|
@defvar LIBS
|
|
The libraries to be used by @code{AC_PROG_LIBTOOL} when it links a
|
|
program. If this is not set, @code{AC_PROG_LIBTOOL} will not use any
|
|
such flags. It affects only the way @code{AC_PROG_LIBTOOL} runs tests,
|
|
not the produced @code{libtool}.
|
|
@end defvar
|
|
|
|
@defvar NM
|
|
Program to use rather than checking for @code{nm}.
|
|
@end defvar
|
|
|
|
@defvar RANLIB
|
|
Program to use rather than checking for @code{ranlib}.
|
|
@end defvar
|
|
|
|
@defvar LN_S
|
|
A command that creates a link of a program, a soft-link if possible, a
|
|
hard-link otherwise. @code{AC_PROG_LIBTOOL} will check for a suitable
|
|
program if this variable is not set.
|
|
@end defvar
|
|
|
|
@defvar DLLTOOL
|
|
Program to use rather than checking for @code{dlltool}. Only meaningful
|
|
for Cygwin/MS-Windows.
|
|
@end defvar
|
|
|
|
@defvar OBJDUMP
|
|
Program to use rather than checking for @code{objdump}. Only meaningful
|
|
for Cygwin/MS-Windows.
|
|
@end defvar
|
|
|
|
@defvar AS
|
|
Program to use rather than checking for @code{as}. Only used on
|
|
Cygwin/MS-Windows at the moment.
|
|
@end defvar
|
|
|
|
@pindex aclocal
|
|
When you invoke the @code{libtoolize} program (@pxref{Invoking
|
|
libtoolize}), it will tell you where to find a definition of
|
|
@code{AC_PROG_LIBTOOL}. If you use Automake, the @code{aclocal} program
|
|
will automatically add @code{AC_PROG_LIBTOOL} support to your
|
|
@code{configure} script.
|
|
|
|
Nevertheless, it is advisable to include a copy of @file{libtool.m4} in
|
|
@file{acinclude.m4}, so that, even if @file{aclocal.m4} and
|
|
@file{configure} are rebuilt for any reason, the appropriate libtool
|
|
macros will be used. The alternative is to hope the user will have a
|
|
compatible version of @file{libtool.m4} installed and accessible for
|
|
@code{aclocal}. This may lead to weird errors when versions don't
|
|
match.
|
|
|
|
@node Distributing
|
|
@section Including libtool in your package
|
|
|
|
In order to use libtool, you need to include the following files with
|
|
your package:
|
|
|
|
@table @file
|
|
@item config.guess
|
|
@pindex config.guess
|
|
Attempt to guess a canonical system name.
|
|
|
|
@item config.sub
|
|
@pindex config.sub
|
|
Canonical system name validation subroutine script.
|
|
|
|
@item ltmain.sh
|
|
@pindex ltmain.sh
|
|
A generic script implementing basic libtool functionality.
|
|
@end table
|
|
|
|
Note that the libtool script itself should @emph{not} be included with
|
|
your package. @xref{Configuring}.
|
|
|
|
You should use the @code{libtoolize} program, rather than manually
|
|
copying these files into your package.
|
|
|
|
@menu
|
|
* Invoking libtoolize:: @code{libtoolize} command line options.
|
|
* Autoconf .o macros:: Autoconf macros that set object file names.
|
|
@end menu
|
|
|
|
@node Invoking libtoolize
|
|
@subsection Invoking @code{libtoolize}
|
|
@pindex libtoolize
|
|
@cindex libtoolize command options
|
|
@cindex command options, libtoolize
|
|
@cindex options, libtoolize command
|
|
|
|
The @code{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 @code{libtoolize} program has the following synopsis:
|
|
|
|
@example
|
|
libtoolize [@var{option}]@dots{}
|
|
@end example
|
|
|
|
@noindent
|
|
and accepts the following options:
|
|
|
|
@table @samp
|
|
@item --automake
|
|
Work silently, and assume that Automake libtool support is used.
|
|
|
|
@samp{libtoolize --automake} is used by Automake to add libtool files to
|
|
your package, when @code{AC_PROG_LIBTOOL} appears in your
|
|
@file{configure.in}.
|
|
|
|
@item --copy
|
|
@itemx -c
|
|
Copy files from the libtool data directory rather than creating
|
|
symlinks.
|
|
|
|
@item --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 @code{less} (or
|
|
@code{more}) or redirect to a file.
|
|
|
|
@item --dry-run
|
|
@itemx -n
|
|
Don't run any commands that modify the file system, just print them
|
|
out.
|
|
|
|
@item --force
|
|
@itemx -f
|
|
Replace existing libtool files. By default, @code{libtoolize} won't
|
|
overwrite existing files.
|
|
|
|
@item --help
|
|
Display a help message and exit.
|
|
|
|
@item --ltdl
|
|
Install libltdl in a subdirectory of your package.
|
|
|
|
@item --ltdl-tar
|
|
Add the file libltdl.tar.gz to your package.
|
|
|
|
@item --version
|
|
Print @code{libtoolize} version information and exit.
|
|
@end table
|
|
|
|
@findex AC_CONFIG_AUX_DIR
|
|
If @code{libtoolize} detects an explicit call to
|
|
@code{AC_CONFIG_AUX_DIR} (@pxref{Input, , The Autoconf Manual,
|
|
autoconf, The Autoconf Manual}) in your @file{configure.in}, it
|
|
will put the files in the specified directory.
|
|
|
|
@code{libtoolize} displays hints for adding libtool support to your
|
|
package, as well.
|
|
|
|
@node Autoconf .o macros
|
|
@subsection Autoconf @samp{.o} macros
|
|
|
|
The Autoconf package comes with a few macros that run tests, then set a
|
|
variable corresponding to the name of an object file. Sometimes it is
|
|
necessary to use corresponding names for libtool objects.
|
|
|
|
Here are the names of variables that list libtool objects:
|
|
|
|
@defvar LTALLOCA
|
|
@findex AC_FUNC_ALLOCA
|
|
Substituted by @code{AC_FUNC_ALLOCA} (@pxref{Particular Functions, Particular
|
|
Function Checks, The Autoconf Manual, autoconf, The Autoconf
|
|
Manual}). Is either empty, or contains @samp{alloca.lo}.
|
|
@end defvar
|
|
|
|
@defvar LTLIBOBJS
|
|
@findex AC_REPLACE_FUNCS
|
|
Substituted by @code{AC_REPLACE_FUNCS} (@pxref{Generic Functions, Generic
|
|
Function Checks, The Autoconf Manual, autoconf, The Autoconf
|
|
Manual}), and a few other functions.
|
|
@end defvar
|
|
|
|
Unfortunately, the stable release of Autoconf (2.13, at the time of
|
|
this writing) does not have any way for libtool to provide support for
|
|
these variables. So, if you depend on them, use the following code
|
|
immediately before the call to @code{AC_OUTPUT} in your
|
|
@file{configure.in}:
|
|
|
|
@example
|
|
LTLIBOBJS=`echo "$LIBOBJS" | sed 's/\.[^.]* /.lo /g;s/\.[^.]*$/.lo/'`
|
|
AC_SUBST(LTLIBOBJS)
|
|
LTALLOCA=`echo "$ALLOCA" | sed 's/\.[^.]* /.lo /g;s/\.[^.]*$/.lo/'`
|
|
AC_SUBST(LTALLOCA)
|
|
AC_OUTPUT(@dots{})
|
|
@end example
|
|
|
|
@node Static-only libraries
|
|
@section Static-only libraries
|
|
@cindex debugging libraries
|
|
@cindex developing libraries
|
|
@cindex double-compilation, avoiding
|
|
@cindex avoiding shared libraries
|
|
@cindex eliding shared libraries
|
|
@cindex using shared libraries, not
|
|
@cindex shared libraries, not using
|
|
@cindex time, saving
|
|
@cindex saving time
|
|
|
|
When you are developing a package, it is often worthwhile to configure
|
|
your package with the @samp{--disable-shared} flag, or to override the
|
|
defaults for @code{AC_PROG_LIBTOOL} by using the
|
|
@code{AC_DISABLE_SHARED} Autoconf macro (@pxref{AC_PROG_LIBTOOL, , The
|
|
@code{AC_PROG_LIBTOOL} macro}). This prevents libtool from building
|
|
shared libraries, which has several advantages:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
compilation is twice as fast, which can speed up your development cycle,
|
|
|
|
@item
|
|
debugging is easier because you don't need to deal with any complexities
|
|
added by shared libraries, and
|
|
|
|
@item
|
|
you can see how libtool behaves on static-only platforms.
|
|
@end itemize
|
|
|
|
You may want to put a small note in your package @file{README} to let
|
|
other developers know that @samp{--disable-shared} can save them time.
|
|
The following example note is taken from the GIMP@footnote{GNU Image
|
|
Manipulation Program, for those who haven't taken the plunge. See
|
|
@url{http://www.gimp.org/}.} distribution @file{README}:
|
|
|
|
@example
|
|
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 @samp{--disable-shared} option to @file{configure}.
|
|
@end example
|
|
|
|
@node Versioning
|
|
@chapter Library interface versions
|
|
@cindex dynamic dependencies
|
|
@cindex dependency versioning
|
|
@cindex shared library 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
|
|
@code{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.
|
|
@end menu
|
|
|
|
@node Interfaces
|
|
@section What are library interfaces?
|
|
@cindex library interfaces
|
|
|
|
Interfaces for libraries may be any of the following (and more):
|
|
|
|
@itemize @bullet
|
|
@item
|
|
global variables: both names and types
|
|
|
|
@item
|
|
global functions: argument types and number, return types, and function names
|
|
|
|
@item
|
|
standard input, standard output, standard error, and file formats
|
|
|
|
@item
|
|
sockets, pipes, and other inter-process communication protocol formats
|
|
@end itemize
|
|
|
|
Note that static functions do not count as interfaces, because they are
|
|
not directly available to the user of the library.
|
|
|
|
@node Libtool versioning
|
|
@section Libtool's versioning system
|
|
@cindex libtool library versions
|
|
@cindex formal versioning
|
|
@cindex versioning, formal
|
|
|
|
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 (@var{first-interface}, @var{last-interface}).
|
|
|
|
The dynamic linker is guaranteed that if a library supports @emph{every}
|
|
interface number between @var{first-interface} and @var{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 @file{libhello} supports interfaces 5, 16, 17, 18, and 19, and that
|
|
libtool is used to link @file{test} against @file{libhello}.
|
|
|
|
Libtool encodes the numbers 5 and 19 in @file{test}, and the dynamic
|
|
linker will only link @file{test} against libraries that support
|
|
@emph{every} interface between 5 and 19. So, the dynamic linker refuses
|
|
to link @file{test} against @file{libhello}!
|
|
|
|
In order to eliminate this problem, libtool only allows libraries to
|
|
declare consecutive interface numbers. So, @file{libhello} can declare at
|
|
most that it supports interfaces 16 through 19. Then, the dynamic
|
|
linker will link @file{test} against @file{libhello}.
|
|
|
|
So, libtool library versions are described by three integers:
|
|
|
|
@table @var
|
|
@item current
|
|
The most recent interface number that this library implements.
|
|
|
|
@item revision
|
|
The implementation number of the @var{current} interface.
|
|
|
|
@item 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 @code{@var{current} -
|
|
@var{age}} to @code{@var{current}}.
|
|
@end table
|
|
|
|
If two libraries have identical @var{current} and @var{age} numbers,
|
|
then the dynamic linker chooses the library with the greater
|
|
@var{revision} number.
|
|
|
|
@node Updating version info
|
|
@section Updating library version information
|
|
|
|
If you want to use libtool's versioning system, then you must specify
|
|
the version information to libtool using the @samp{-version-info} flag
|
|
during link mode (@pxref{Link mode}).
|
|
|
|
This flag accepts an argument of the form
|
|
@samp{@var{current}[:@var{revision}[:@var{age}]]}. So, passing
|
|
@samp{-version-info 3:12:1} sets @var{current} to 3, @var{revision} to
|
|
12, and @var{age} to 1.
|
|
|
|
If either @var{revision} or @var{age} are omitted, they default to 0.
|
|
Also note that @var{age} must be less than or equal to the @var{current}
|
|
interface number.
|
|
|
|
Here are a set of rules to help you update your library version
|
|
information:
|
|
|
|
@enumerate 1
|
|
@item
|
|
Start with version information of @samp{0:0:0} for each libtool library.
|
|
|
|
@item
|
|
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.
|
|
|
|
@item
|
|
If the library source code has changed at all since the last update,
|
|
then increment @var{revision} (@samp{@var{c}:@var{r}:@var{a}} becomes
|
|
@samp{@var{c}:@math{r+1}:@var{a}}).
|
|
|
|
@item
|
|
If any interfaces have been added, removed, or changed since the last
|
|
update, increment @var{current}, and set @var{revision} to 0.
|
|
|
|
@item
|
|
If any interfaces have been added since the last public release, then
|
|
increment @var{age}.
|
|
|
|
@item
|
|
If any interfaces have been removed since the last public release, then
|
|
set @var{age} to 0.
|
|
@end enumerate
|
|
|
|
@strong{@emph{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 @samp{-release} flag (@pxref{Release numbers}), but be
|
|
warned that every release of your package will not be binary compatible
|
|
with any other release.
|
|
|
|
@node Release numbers
|
|
@section 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:
|
|
|
|
@example
|
|
trick$ @kbd{ls /usr/lib/libbfd*}
|
|
/usr/lib/libbfd.a /usr/lib/libbfd.so.2.7.0.2
|
|
/usr/lib/libbfd.so
|
|
trick$
|
|
@end example
|
|
|
|
On @samp{trick}, @file{/usr/lib/libbfd.so} is a symbolic link to
|
|
@file{libbfd.so.2.7.0.2}, which was distributed as a part of
|
|
@samp{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 @samp{-release}
|
|
flag in order to set release information for libraries which you do not
|
|
want to use @samp{-version-info}. For the @file{libbfd} example, the
|
|
next release which uses libtool should be built with @samp{-release
|
|
2.9.0}, which will produce the following files on GNU/Linux:
|
|
|
|
@example
|
|
trick$ @kbd{ls /usr/lib/libbfd*}
|
|
/usr/lib/libbfd-2.9.0.so /usr/lib/libbfd.a
|
|
/usr/lib/libbfd.so
|
|
trick$
|
|
@end example
|
|
|
|
In this case, @file{/usr/lib/libbfd.so} is a symbolic link to
|
|
@file{libbfd-2.9.0.so}. This makes it obvious that the user is dealing
|
|
with @samp{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 @samp{-release} for
|
|
package-internal libraries or for ones whose interfaces change very
|
|
frequently.
|
|
|
|
@node Library tips
|
|
@chapter Tips for interface design
|
|
@cindex library interfaces, design
|
|
@cindex design of library interfaces
|
|
|
|
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, which may
|
|
help you in your exploits:
|
|
|
|
@table @asis
|
|
@item Plan ahead
|
|
Try to make every interface truly minimal, so that you won't need to
|
|
delete entry points very often.
|
|
|
|
@item Avoid interface changes
|
|
@cindex renaming interface functions
|
|
Some people love redesigning and changing entry points just for the heck
|
|
of it (note: @emph{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.
|
|
|
|
@item Use opaque data types
|
|
@cindex 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
|
|
(which 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.
|
|
|
|
@item Use header files
|
|
@cindex 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 (@pxref{C header files}).
|
|
|
|
@item Use the @code{static} keyword (or equivalent) whenever possible
|
|
@cindex global functions
|
|
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@dots{} your users cannot access them, so they
|
|
aren't interface changes.
|
|
@end table
|
|
|
|
@menu
|
|
* C header files:: How to write portable include files.
|
|
@end menu
|
|
|
|
@node C header files
|
|
@section Writing C header files
|
|
@cindex portable C headers
|
|
@cindex C header files, portable
|
|
@cindex include files, portable
|
|
|
|
Writing portable C header files can be difficult, since they may be read
|
|
by different types of compilers:
|
|
|
|
@table @asis
|
|
@item 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 @code{extern "C"} directive, so that the
|
|
names aren't mangled. @xref{C++ libraries}, for other issues relevant
|
|
to using C++ with libtool.
|
|
|
|
@item 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 @code{#include}d.
|
|
|
|
@item non-ANSI C compilers
|
|
Non-ANSI compilers will report errors if functions are prototyped.
|
|
@end table
|
|
|
|
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.
|
|
|
|
@file{foo.h} in the @file{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:
|
|
|
|
@example
|
|
/* 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
|
|
@end example
|
|
|
|
These macros are used in @file{foo.h} as follows:
|
|
|
|
@example
|
|
#ifndef FOO_H
|
|
#define FOO_H 1
|
|
|
|
/* The above macro definitions. */
|
|
#include "@dots{}"
|
|
|
|
BEGIN_C_DECLS
|
|
|
|
int foo PARAMS((void));
|
|
int hello PARAMS((void));
|
|
|
|
END_C_DECLS
|
|
|
|
#endif /* !FOO_H */
|
|
@end example
|
|
|
|
Note that the @file{#ifndef FOO_H} prevents the body of @file{foo.h}
|
|
from being read more than once in a given compilation.
|
|
|
|
Also the only thing that must go outside the
|
|
@code{BEGIN_C_DECLS}/@code{END_C_DECLS} pair are @code{#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 of these macros around the majority of the header contents.
|
|
|
|
You should use these definitions of @code{PARAMS}, @code{BEGIN_C_DECLS},
|
|
and @code{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@footnote{We used to recommend @code{__P},
|
|
@code{__BEGIN_DECLS} and @code{__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.}.
|
|
|
|
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:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
Pre-ANSI compilers do not always support the @code{void *} generic
|
|
pointer type, and so need to use @code{char *} in its place.
|
|
|
|
@item
|
|
The @code{const}, @code{inline} and @code{signed} keywords are not
|
|
supported by some compilers, especially pre-ANSI compilers.
|
|
|
|
@item
|
|
The @code{long double} type is not supported by many compilers.
|
|
@end itemize
|
|
|
|
@node Inter-library dependencies
|
|
@chapter Inter-library dependencies
|
|
@cindex dependencies between libraries
|
|
@cindex 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 @dfn{inter-library dependency} is one in which a library depends on
|
|
other libraries. For example, if the libtool library @file{libhello}
|
|
uses the @code{cos} function, then it has an inter-library dependency
|
|
on @file{libm}, the math library that implements @code{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 @file{lib@var{name}} that
|
|
your own library depends on, simply add a corresponding
|
|
@code{-l@var{name}} option to the link line when you create your
|
|
library. To make an example of our
|
|
@file{libhello} that depends on @file{libm}:
|
|
|
|
@example
|
|
burger$ @kbd{libtool gcc -g -O -o libhello.la foo.lo hello.lo \
|
|
-rpath /usr/local/lib -lm}
|
|
burger$
|
|
@end example
|
|
|
|
When you link a program against @file{libhello}, you don't need to
|
|
specify the same @samp{-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 AIX, do not even allow you this
|
|
flexibility. In order to build a shared library, it must be entirely
|
|
self-contained (that is, have references only to symbols that are found
|
|
in the @samp{.lo} files or the specified @samp{-l} libraries), and you
|
|
need to specify the @var{-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.
|
|
|
|
@node Dlopened modules
|
|
@chapter Dlopened modules
|
|
@findex dlopen
|
|
@findex dlsym
|
|
@findex dlclose
|
|
@findex shl_load
|
|
@cindex dynamic linking, applications
|
|
@cindex dlopening modules
|
|
@cindex modules, dynamic
|
|
@cindex application-level dynamic linking
|
|
|
|
It can sometimes be confusing to discuss @dfn{dynamic linking}, because
|
|
the term is used to refer to two different concepts:
|
|
|
|
@enumerate 1
|
|
@item
|
|
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.
|
|
|
|
@item
|
|
The application calling functions such as @code{dlopen},@footnote{HP-UX,
|
|
to be different, uses a function named @code{shl_load}.} which load
|
|
arbitrary, user-specified modules at runtime. This type of dynamic
|
|
linking is explicitly controlled by the application.
|
|
@end enumerate
|
|
|
|
To mitigate confusion, this manual refers to the second type of dynamic
|
|
linking as @dfn{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.
|
|
|
|
As of version @value{VERSION}, libtool provides support for dlopened
|
|
modules. However, you should indicate that your package is willing to
|
|
use such support, by using the macro @samp{AC_LIBTOOL_DLOPEN} in
|
|
@file{configure.in}. If this macro is not used (or it is used
|
|
@emph{after} @samp{AC_PROG_LIBTOOL}), 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.
|
|
* Finding the dlname:: Choosing the right file to @code{dlopen}.
|
|
* Dlopen issues:: Unresolved problems that need your attention.
|
|
@end menu
|
|
|
|
@node Building modules
|
|
@section Building modules to dlopen
|
|
|
|
On some operating systems, a program symbol must be specially declared
|
|
in order to be dynamically resolved with the @code{dlsym} (or
|
|
equivalent) function.
|
|
|
|
Libtool provides the @samp{-export-dynamic} and @samp{-module}
|
|
link flags (@pxref{Link mode}), which do this 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, @file{libhello},
|
|
that would later be dlopened by an application, we would add
|
|
@samp{-module} to the other link flags:
|
|
|
|
@example
|
|
burger$ @kbd{libtool gcc -module -o libhello.la foo.lo \
|
|
hello.lo -rpath /usr/local/lib -lm}
|
|
burger$
|
|
@end example
|
|
|
|
If symbols from your @emph{executable} are needed to satisfy unresolved
|
|
references in a library you want to dlopen you will have to use the flag
|
|
@samp{-export-dynamic}.
|
|
You should use @samp{-export-dynamic} while linking the executable that calls
|
|
dlopen:
|
|
|
|
@example
|
|
burger$ @kbd{libtool gcc -export-dynamic -o hell-dlopener main.o}
|
|
burger$
|
|
@end example
|
|
|
|
@node Dlpreopening
|
|
@section Dlpreopening
|
|
|
|
Libtool provides special support for dlopening libtool object and
|
|
libtool library files, so that their symbols can be resolved @emph{even
|
|
on platforms without any @code{dlopen} and @code{dlsym}
|
|
functions}.
|
|
|
|
Consider the following alternative ways of loading code into your
|
|
program, in order of increasing ``laziness'':
|
|
|
|
@enumerate 1
|
|
@item
|
|
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 linker refuses to create the executable.
|
|
|
|
@item
|
|
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 linker refuses
|
|
to link the executable.
|
|
|
|
@item
|
|
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.
|
|
|
|
@item
|
|
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.
|
|
@end enumerate
|
|
|
|
Libtool emulates @samp{-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 @samp{-dlopen} or @samp{-dlpreopen}
|
|
flags when you link your program (@pxref{Link mode}).
|
|
|
|
@deftypefn {Structure} {struct} lt_dlsymlist @{ @w{const char *@var{name};} @w{lt_ptr_t @var{address};} @}
|
|
The @var{name} attribute is a null-terminated character string of the
|
|
symbol name, such as @code{"fprintf"}. The @var{address} attribute is a
|
|
generic pointer to the appropriate object, such as @code{&fprintf}.
|
|
@end deftypefn
|
|
|
|
@deftypevar {const lt_dlsymlist *} lt_preloaded_symbols
|
|
An array of @var{lt_symbol} structures, representing all the preloaded
|
|
symbols linked into the program. For each @samp{-dlpreloaded} file
|
|
there is an element with the @var{name} of the file and a @var{address}
|
|
of @code{0}, followed by all symbols exported from this file.
|
|
For the executable itself the special name @@PROGRAM@@ is used.
|
|
The last element has a @var{name} and @var{address} of @code{0}.
|
|
@end deftypevar
|
|
|
|
Some compilers may allow identifiers which 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 @var{lt_preloaded_symbols}.
|
|
|
|
@node Finding the dlname
|
|
@section Finding the correct name to dlopen
|
|
@cindex names of dynamic modules
|
|
@cindex dynamic modules, names
|
|
|
|
After a library has been linked with @samp{-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 @samp{.la} file, and searching
|
|
it for the following lines:
|
|
|
|
@example
|
|
# The name that we can @code{dlopen}.
|
|
dlname='@var{dlname}'
|
|
@end example
|
|
|
|
If @var{dlname} is empty, then the library cannot be dlopened.
|
|
Otherwise, it gives the dlname of the library. So, if the library was
|
|
installed as @file{/usr/local/lib/libhello.la}, and the @var{dlname} was
|
|
@file{libhello.so.3}, then @file{/usr/local/lib/libhello.so.3} should be
|
|
dlopened.
|
|
|
|
If your program uses this approach, then it should search the
|
|
directories listed in the @code{LD_LIBRARY_PATH}@footnote{@code{LIBPATH}
|
|
on AIX, and @code{SHLIB_PATH} on HP-UX.} 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.
|
|
|
|
@node Dlopen issues
|
|
@section Unresolved dlopen issues
|
|
@cindex pitfalls with dlopen
|
|
@cindex dlopening, pitfalls
|
|
@cindex trouble with dlopen
|
|
|
|
The following problems are not solved by using libtool's dlopen support:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
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 (@pxref{Using libltdl}) or develop your
|
|
own alternatives to dlopening dynamic code.
|
|
Most reasonable solutions involve writing wrapper functions for the
|
|
@code{dlopen} family, which do package-specific tricks when dlopening
|
|
is unsupported or not available on a given platform.
|
|
|
|
@item
|
|
There are major differences in implementations of the @code{dlopen}
|
|
family of functions. Some platforms do not even use the same function
|
|
names (notably HP-UX, with its @code{shl_load} family).
|
|
|
|
@item
|
|
The application developer must write a custom search function in order
|
|
to discover the correct module filename to supply to @code{dlopen}.
|
|
@end itemize
|
|
|
|
@node Using libltdl
|
|
@chapter Using libltdl
|
|
@findex libltdl
|
|
@findex dlopen
|
|
@findex dlsym
|
|
@findex dlclose
|
|
@findex dlerror
|
|
@findex shl_load
|
|
@cindex dynamic linking, applications
|
|
@cindex dlopening modules
|
|
@cindex modules, dynamic
|
|
@cindex application-level dynamic linking
|
|
|
|
Libtool provides a small library, called @file{libltdl}, that aims at
|
|
hiding the various difficulties of dlopening libraries from programmers.
|
|
It consists of a header-file and a small C source file that can be
|
|
distributed with applications that need dlopening functionality. On
|
|
some platforms, whose dynamic linkers are too limited for a simple
|
|
implementation of @file{libltdl} services, it requires GNU DLD, or it
|
|
will only emulate dynamic linking with libtool's dlpreopening mechanism.
|
|
|
|
@noindent
|
|
libltdl supports currently the following dynamic linking mechanisms:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
@code{dlopen} (Solaris, Linux and various BSD flavors)
|
|
@item
|
|
@code{shl_load} (HP-UX)
|
|
@item
|
|
@code{LoadLibrary} (Win16 and Win32)
|
|
@item
|
|
@code{load_add_on} (BeOS)
|
|
@item
|
|
GNU DLD (emulates dynamic linking for static libraries)
|
|
@item
|
|
libtool's dlpreopen (see @pxref{Dlpreopening})
|
|
@end itemize
|
|
|
|
@noindent
|
|
libltdl is licensed under the terms of the GNU Library General Public License,
|
|
with the following exception:
|
|
|
|
@quotation
|
|
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.
|
|
@end quotation
|
|
|
|
@menu
|
|
* Libltdl interface:: How to use libltdl in your programs.
|
|
* Modules for libltdl:: Creating modules that can be @code{dlopen}ed.
|
|
* Distributing libltdl:: How to distribute libltdl with your package.
|
|
* Module loaders for libltdl:: Creating user defined module loaders.
|
|
@end menu
|
|
|
|
@node Libltdl interface
|
|
@section How to use libltdl in your programs
|
|
|
|
@noindent
|
|
The libltdl API is similar to the dlopen interface of Solaris and Linux,
|
|
which is very simple but powerful.
|
|
|
|
@noindent
|
|
To use libltdl in your program you have to include the header file @file{ltdl.h}:
|
|
|
|
@example
|
|
#include <ltdl.h>
|
|
@end example
|
|
|
|
@noindent
|
|
Note that libltdl is not threadsafe, i.e. a multithreaded application
|
|
has to use a mutex for libltdl. It was reported that GNU/Linux's glibc
|
|
2.0's @code{dlopen} with @samp{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, @samp{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.
|
|
|
|
@noindent
|
|
The following types are defined in @file{ltdl.h}:
|
|
|
|
@deftp {Type} lt_ptr_t
|
|
@code{lt_ptr_t} is a generic pointer.
|
|
@end deftp
|
|
|
|
@deftp {Type} lt_dlhandle
|
|
@code{lt_dlhandle} is a module "handle".
|
|
Every lt_dlopened module has a handle associated with it.
|
|
@end deftp
|
|
|
|
@deftypefn {Type} {struct} lt_dlinfo @{ @w{char *@var{filename};} @w{char *@var{name};} @w{int @var{ref_count};} @}
|
|
@code{lt_dlinfo} is used to store information about a module.
|
|
The @var{filename} attribute is a null-terminated character string of the
|
|
real module file name. If the module is a libtool module then @var{name}
|
|
is its module name (e.g. @code{"libfoo"} for @code{"dir/libfoo.la"}),
|
|
otherwise it is set to @code{NULL}.
|
|
The @var{ref_count} attribute is a reference counter that describes how often
|
|
the same module is currently loaded.
|
|
@end deftypefn
|
|
|
|
@deftp {Type} lt_dlsymlist
|
|
@code{lt_dlsymlist} is a symbol list for dlpreopened modules.
|
|
This structure is described in @pxref{Dlpreopening}.
|
|
@end deftp
|
|
|
|
@page
|
|
@noindent
|
|
libltdl provides the following functions:
|
|
|
|
@deftypefun 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.
|
|
@end deftypefun
|
|
|
|
@deftypefun 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 @code{lt_dlinit} has been successfully called.
|
|
Return 0 on success, otherwise the number of errors.
|
|
@end deftypefun
|
|
|
|
@deftypefun lt_dlhandle lt_dlopen (const char *@var{filename})
|
|
Open the module with the file name @var{filename} and return a
|
|
handle for it. @code{lt_dlopen} is able to open libtool dynamic
|
|
modules, preloaded static modules, the program itself and
|
|
native dynamic libraries.
|
|
|
|
Unresolved symbols in the module are resolved using its dependency
|
|
libraries (not implemented yet) and previously dlopened modules. If the
|
|
executable using this module was linked with the @code{-export-dynamic}
|
|
flag, then the global symbols in the executable will also be used to
|
|
resolve references in the module.
|
|
|
|
If @var{filename} is @code{NULL} and the program was linked with
|
|
@code{-export-dynamic} or @code{-dlopen self}, @code{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 @var{filename} does
|
|
not have a directory component it will additionally search in the
|
|
following search paths for the module (in the order as follows):
|
|
|
|
@enumerate 1
|
|
@item user-defined search path:
|
|
This search path can be set by the program using the
|
|
functions @code{lt_dlsetsearchpath} and @code{lt_dladdsearchdir}.
|
|
|
|
@item libltdl's search path:
|
|
This search path is the value of the environment variable
|
|
@var{LTDL_LIBRARY_PATH}.
|
|
|
|
@item system library search path:
|
|
The system dependent library search path
|
|
(e.g. on Linux it is @var{LD_LIBRARY_PATH}).
|
|
@end enumerate
|
|
|
|
Each search path must be a colon-separated list of absolute directories,
|
|
for example, @code{"/usr/lib/mypkg:/lib/foo"}.
|
|
|
|
If the same module is loaded several times, the same handle is returned.
|
|
If @code{lt_dlopen} fails for any reason, it returns @code{NULL}.
|
|
@end deftypefun
|
|
|
|
@deftypefun lt_dlhandle lt_dlopenext (const char *@var{filename})
|
|
The same as @code{lt_dlopen}, except that it tries to append
|
|
different file name extensions to the file name.
|
|
If the file with the file name @var{filename} cannot be found
|
|
libltdl tries to append the following extensions:
|
|
|
|
@enumerate 1
|
|
@item the libtool archive extension @samp{.la}
|
|
@item the extension used for native dynamic libraries on the host platform,
|
|
e.g., @samp{.so}, @samp{.sl}, etc.
|
|
@end enumerate
|
|
|
|
This lookup strategy was designed to allow programs that don't
|
|
have knowledge about native dynamic libraries naming conventions
|
|
to be able to @code{dlopen} such libraries as well as libtool modules
|
|
transparently.
|
|
@end deftypefun
|
|
|
|
@deftypefun int lt_dlclose (lt_dlhandle @var{handle})
|
|
Decrement the reference count on the module @var{handle}.
|
|
If it drops to zero and no other module depends on this module,
|
|
then the module is unloaded.
|
|
Return 0 on success.
|
|
@end deftypefun
|
|
|
|
@deftypefun lt_ptr_t lt_dlsym (lt_dlhandle @var{handle}, const char *@var{name})
|
|
Return the address in the module @var{handle}, where the symbol given
|
|
by the null-terminated string @var{name} is loaded.
|
|
If the symbol cannot be found, @code{NULL} is returned.
|
|
@end deftypefun
|
|
|
|
@deftypefun {const char *} lt_dlerror (void)
|
|
Return a human readable string describing the most
|
|
recent error that occurred from any of libltdl's functions.
|
|
Return @code{NULL} if no errors have occurred since initialization
|
|
or since it was last called.
|
|
@end deftypefun
|
|
|
|
@deftypefun int lt_dlpreload (const lt_dlsymlist *@var{preloaded})
|
|
Register the list of preloaded modules @var{preloaded}.
|
|
If @var{preloaded} is @code{NULL}, then all previously registered
|
|
symbol lists, except the list set by @code{lt_dlpreload_default},
|
|
are deleted. Return 0 on success.
|
|
@end deftypefun
|
|
|
|
@deftypefun int lt_dlpreload_default (const lt_dlsymlist *@var{preloaded})
|
|
Set the default list of preloaded modules to @var{preloaded}, which
|
|
won't be deleted by @code{lt_dlpreload}. Note that this function does
|
|
@emph{not} require libltdl to be initialized using @code{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 @code{LTDL_SET_PRELOADED_SYMBOLS}.
|
|
|
|
Return 0 on success.
|
|
@end deftypefun
|
|
|
|
@defmac 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.
|
|
|
|
@example
|
|
#include <ltdl.h>
|
|
|
|
int main() @{
|
|
/* ... */
|
|
LTDL_SET_PRELOADED_SYMBOLS();
|
|
/* ... */
|
|
@}
|
|
@end example
|
|
@end defmac
|
|
|
|
@deftypefun int lt_dladdsearchdir (const char *@var{search_dir})
|
|
Add the search directory @var{search_dir} to the user-defined library
|
|
search path. Return 0 on success.
|
|
@end deftypefun
|
|
|
|
@deftypefun int lt_dlsetsearchpath (const char *@var{search_path})
|
|
Replace the current user-defined library search path with
|
|
@var{search_path}, which must be a colon-separated list of absolute
|
|
directories. Return 0 on success.
|
|
@end deftypefun
|
|
|
|
@deftypefun {const char *} lt_dlgetsearchpath (void)
|
|
Return the current user-defined library search path.
|
|
@end deftypefun
|
|
|
|
@deftypefun {const lt_dlinfo *} lt_dlgetinfo (lt_dlhandle @var{handle})
|
|
Return a pointer to a struct that contains some information about
|
|
the module @var{handle}. The contents of the struct must not be modified.
|
|
Return @code{NULL} on failure.
|
|
@end deftypefun
|
|
|
|
@deftypefun int lt_dlforeach (int (*@var{func})(lt_dlhandle @var{handle}, lt_ptr_t @var{data}), lt_ptr_t @var{data})
|
|
For each loaded module call the function @var{func}. The argument
|
|
@var{handle} is the handle of one of the loaded modules, @var{data} is
|
|
the @var{data} argument passed to @code{lt_dlforeach}.
|
|
As soon as @var{func} returns a non-zero value for one of the handles,
|
|
@code{lt_dlforeach} will stop calling @var{func} and immediately return 1.
|
|
Otherwise 0 is returned.
|
|
@end deftypefun
|
|
|
|
@deftypevar {lt_ptr_t (*} lt_dlmalloc ) (size_t @var{size})
|
|
@deftypevarx {void (*} lt_dlfree ) (lt_ptr_t @var{ptr})
|
|
These variables are set to @code{malloc} and @code{free}, by default,
|
|
but you can set them to any other functions that provides equivalent
|
|
functionality. However, you must not modify their values after calling
|
|
any libltdl function other than @code{lt_dlpreopen_default} or the macro
|
|
@code{LTDL_SET_PRELOADED_SYMBOLS}.
|
|
@end deftypevar
|
|
|
|
@node Modules for libltdl
|
|
@section Creating modules that can be @code{dlopen}ed
|
|
|
|
Libtool modules are like normal libtool libraries with a few exceptions:
|
|
|
|
You have to link the module with libtool's @samp{-module} switch,
|
|
and you should link any program that is intended to dlopen the module with
|
|
@samp{-dlopen modulename.la} so that libtool can dlpreopen the module
|
|
on platforms which don't 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 @pxref{Versioning} for a specific module
|
|
you should link it with the @samp{-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_" (@samp{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 which
|
|
don't use a prefix so that you can also dlopen non-libtool modules.
|
|
|
|
@file{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.
|
|
|
|
@example
|
|
/* 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();
|
|
@}
|
|
@end example
|
|
|
|
@noindent
|
|
The @file{Makefile.am} contains the necessary rules to build the
|
|
module @file{foo1.la}:
|
|
|
|
@example
|
|
...
|
|
lib_LTLIBRARIES = foo1.la
|
|
|
|
foo1_la_SOURCES = foo1.c
|
|
foo1_la_LDFLAGS = -module
|
|
...
|
|
@end example
|
|
|
|
@node Distributing libltdl
|
|
@section 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.
|
|
In this case, you must decide whether to manually add the @code{ltdl}
|
|
objects to your package, or else which flavor of libltdl you want to use:
|
|
a convenience library or an installable libtool library.
|
|
|
|
The most simplistic way to add @code{libltdl} to your package is to copy
|
|
the source files, @file{ltdl.c} and @file{ltdl.h}, to a source directory
|
|
withing 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 @file{ltdl.m4}. You must ensure that they are available in
|
|
@file{aclocal.m4} before you run autoconf -- by appending the contents
|
|
of @file{ltdl.m4} to @file{acinclude.m4}, if you are using automake, or
|
|
to @file{aclocal.m4} if you are not. Having made the macros available,
|
|
you must add a call to the @samp{AC_LIB_LTDL} macro to your package's
|
|
@file{configure.in} to perform the configure time checks required to
|
|
build @file{ltdl.o} correctly. This method has problems if you then try
|
|
to link the package binaries with an installed libltdl, or a library
|
|
which depends on libltdl: you may have problems with duplicate symbol
|
|
definitions.
|
|
|
|
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
|
|
will not overwrite a pre-installed version of libltdl a user might have.
|
|
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 an 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 these libraries, because you may get duplicate
|
|
symbols. In general you can safely use the convenience library in programs
|
|
which don't depend on other libraries that might use libltdl too.
|
|
In order to enable this flavor of libltdl, you should add the
|
|
line @samp{AC_LIBLTDL_CONVENIENCE} to your @file{configure.in},
|
|
@emph{before} @samp{AC_PROG_LIBTOOL}.
|
|
|
|
In order to select the installable version of libltdl, you should add a
|
|
call of the macro @samp{AC_LIBLTDL_INSTALLABLE} to your
|
|
@file{configure.in} @emph{before} @samp{AC_PROG_LIBTOOL}. This macro
|
|
will check whether libltdl is already installed and, if not, request the
|
|
libltdl embedded in your package to be built and installed. Note,
|
|
however, that no version checking is performed. The user may override
|
|
the test and determine that the libltdl embedded must be installed,
|
|
regardless of the existence of another version, using the configure
|
|
switch @samp{--enable-ltdl-install}.
|
|
|
|
In order to embed libltdl into your package, just add @samp{--ltdl} to
|
|
the @code{libtoolize} command line. It will copy the libltdl sources
|
|
to a subdirectory @samp{libltdl} in your package.
|
|
Both macros accept an optional argument to specify the location
|
|
of the @samp{libltdl} directory. By the default both macros assume that it
|
|
is @samp{$@{top_srcdir@}/libltdl}.
|
|
|
|
Whatever macro you use, it is up to you to ensure that your
|
|
@file{configure.in} will configure libltdl, using
|
|
@samp{AC_CONFIG_SUBDIRS}, and that your @file{Makefile}s will start
|
|
sub-makes within libltdl's directory, using automake's @var{SUBDIRS},
|
|
for example. Both macros define the shell variables @var{LIBLTDL}, to
|
|
the link flag that you should use to link with libltdl, and
|
|
@var{INCLTDL}, to the preprocessor flag that you should use to compile
|
|
with programs that include @file{ltdl.h}. It is up to you to use
|
|
@samp{AC_SUBST} to ensure that this variable will be available in
|
|
@file{Makefile}s, or add them to variables that are @samp{AC_SUBST}ed by
|
|
default, such as @var{LIBS} and @var{CPPFLAGS}.
|
|
|
|
If you're using the convenience libltdl, @var{LIBLTDL} will be the
|
|
pathname for the convenience version of libltdl and @var{INCLTDL} will be
|
|
@samp{-I} followed by the directory that contains libltdl, both starting
|
|
with @samp{$@{top_builddir@}/} or @samp{$@{top_srcdir@}/}, respectively.
|
|
|
|
If you request an installed version of libltdl and one is
|
|
found@footnote{Even if libltdl is installed,
|
|
@samp{AC_LIBLTDL_INSTALLABLE} may fail to detect it, if libltdl depends
|
|
on symbols provided by libraries other than the C library. In this
|
|
case, it will needlessly build and install libltdl.}, @var{LIBLTDL} will
|
|
be set to @samp{-lltdl} and @var{INCLTDL} will be empty (which is just a
|
|
blind assumption that @file{ltdl.h} is somewhere in the include path if
|
|
libltdl is in the library path). If an installable version of libltdl
|
|
must be built, its pathname, starting with @samp{$@{top_builddir@}/},
|
|
will be stored in @var{LIBLTDL}, and @var{INCLTDL} will be set just like
|
|
in the case of convenience library.
|
|
|
|
So, when you want to link a program with libltdl, be it a convenience,
|
|
installed or installable library, just compile with @samp{$(INCLTDL)}
|
|
and link it with @samp{$(LIBLTDL)}, using libtool.
|
|
|
|
You should probably also add @samp{AC_LIBTOOL_DLOPEN} to your
|
|
@file{configure.in} @emph{before} @samp{AC_PROG_LIBTOOL}, otherwise
|
|
libtool will assume no dlopening mechanism is supported, and revert to
|
|
dlpreopening, which is probably not what you want.
|
|
|
|
Avoid using the @code{-static} or @code{-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 the convenience libltdl in
|
|
your package. In order to use the installable variant just replace
|
|
@samp{AC_LIBLTDL_CONVENIENCE} with @samp{AC_LIBLTDL_INSTALLABLE}. We
|
|
assume that libltdl was embedded using @samp{libtoolize --ltdl}.
|
|
|
|
configure.in:
|
|
@example
|
|
...
|
|
dnl Enable building of the convenience library
|
|
dnl and set LIBLTDL accordingly
|
|
AC_LIBLTDL_CONVENIENCE
|
|
dnl Substitute INCLTDL and LIBLTDL in the Makefiles
|
|
AC_SUBST(INCLTDL)
|
|
AC_SUBST(LIBLTDL)
|
|
dnl Check for dlopen support
|
|
AC_LIBTOOL_DLOPEN
|
|
dnl Configure libtool
|
|
AC_PROG_LIBTOOL
|
|
dnl Configure libltdl
|
|
AC_CONFIG_SUBDIRS(libltdl)
|
|
...
|
|
@end example
|
|
|
|
Makefile.am:
|
|
@example
|
|
...
|
|
SUBDIRS = libltdl
|
|
|
|
INCLUDES = $(INCLTDL)
|
|
|
|
myprog_LDFLAGS = -export-dynamic
|
|
# The quotes around -dlopen below fool automake <= 1.4 into accepting it
|
|
myprog_LDADD = $(LIBLTDL) "-dlopen" self "-dlopen" foo1.la
|
|
myprog_DEPENDENCIES = $(LIBLTDL) foo1.la
|
|
...
|
|
@end example
|
|
|
|
@node Module loaders for libltdl
|
|
@section 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 @code{lt_dlopen} will be
|
|
able to use it.
|
|
|
|
Writing a loader involves writing at least three functions which can be
|
|
called by @code{lt_dlopen}, @code{lt_dlsym} and @code{lt_dlclose}.
|
|
Optionally, you can provide a finalisation function to perform any
|
|
cleanup operations when @code{lt_dlexit} executes, and a symbol prefix
|
|
string which will be prepended to any symbols passed to @code{lt_dlsym}.
|
|
These functions must match the function pointer types below, after
|
|
which they can be allocated to an instance of @code{lt_user_dlloader}
|
|
and registered.
|
|
|
|
Registering the loader requires that you choose a name for it, so that it
|
|
can be recognised by @code{lt_dlloader_find} and removed with
|
|
@code{lt_dlloader_remove}. The name you choose must be unique, and not
|
|
already in use by libltdl's builtin loaders:
|
|
|
|
@table @asis
|
|
@item "dlopen"
|
|
The system dynamic library loader, if one exists.
|
|
@item "dld"
|
|
The @sc{gnu} dld loader, if @file{libdld} was installed when libltdl was
|
|
built.
|
|
@item "dlpreload"
|
|
The loader for @code{lt_dlopen}ing of preloaded static modules.
|
|
@end table
|
|
|
|
The prefix "dl" is reserved for loaders supplied with future versions of
|
|
libltdl, so you should not use that for your own loader names.
|
|
|
|
@noindent
|
|
The following types are defined in @file{ltdl.h}:
|
|
|
|
@deftp {Type} lt_module_t
|
|
@code{lt_module_t} is a dlloader dependent module.
|
|
The dynamic module loader extensions communicate using these low
|
|
level types.
|
|
@end deftp
|
|
|
|
@deftp {Type} lt_dlloader_t
|
|
@code{lt_dlloader_t} is a handle for module loader types.
|
|
@end deftp
|
|
|
|
@deftp {Type} lt_dlloader_data_t
|
|
@code{lt_dlloader_data_t} is used for specifying loader instance data.
|
|
@end deftp
|
|
|
|
@deftypefn {Type} {struct} lt_user_dlloader @{@w{const char *@var{sym_prefix};} @w{lt_module_open_t *@var{module_open};}@w{lt_module_close_t *@var{module_close};} @w{lt_find_sym_t *@var{find_sym};} @w{lt_dlloader_exit_t *@var{dlloader_exit};} @w{lt_dlloader_data_t @var{dlloader_data};} @}
|
|
If you want to define a new way to open dynamic modules, and have the
|
|
@code{lt_dlopen} @sc{api} use it, you need to instantiate one of these
|
|
structures and pass it to @code{lt_dlloader_add}. You can pass whatever
|
|
you like in the @var{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.
|
|
@end deftypefn
|
|
|
|
@deftypefn {Type} lt_module_t lt_module_open_t (@w{lt_dlloader_data_t @var{loader_data},} @w{const char *@var{filename}})
|
|
The type of the loader function for an @code{lt_dlloader_t} module
|
|
loader. The value set in the dlloader_data field of the @code{struct
|
|
lt_user_dlloader} structure will be passed into this function in the
|
|
@var{loader_data} parameter. Implementation of such a function should
|
|
attempt to load the named module, and return an @code{lt_module_t}
|
|
suitable for passing in to the associated @code{lt_module_close_t} and
|
|
@code{lt_sym_find_t} function pointers. If the function fails it should
|
|
return @code{NULL}, and set the error message with @code{lt_dlseterror}.
|
|
@end deftypefn
|
|
|
|
@deftypefn {Type} int lt_module_close_t (@w{lt_dlloader_data_t @var{loader_data},} @w{lt_module_t @var{module}})
|
|
The type of the unloader function for a user defined module loader.
|
|
Implementatation of such a function should attempt to release
|
|
any resources tied up by the @var{module} module, and then unload it
|
|
from memory. If the function fails for some reason, set the error
|
|
message with @code{lt_dlseterror} and return non-zero.
|
|
@end deftypefn
|
|
|
|
@deftypefn {Type} lt_ptr_t lt_find_sym_t (@w{lt_dlloader_data_t @var{loader_data},} @w{lt_module_t @var{module},} @w{const char *@var{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
|
|
@var{symbol} in the module @var{module}, or else set the error message
|
|
with @code{lt_dlseterror} and return @code{NULL} if lookup fails.
|
|
@end deftypefn
|
|
|
|
@deftypefn {Type} int lt_dlloader_exit_t (@w{lt_dlloader_data_t @var{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
|
|
@code{dlloader_data} field of the @code{lt_user_dlloader}. If non-@code{NULL},
|
|
the function will be called by @code{lt_dlexit}, and
|
|
@code{lt_dlloader_remove}.
|
|
@end deftypefn
|
|
|
|
For example:
|
|
|
|
@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_dlloader_data_t)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;
|
|
@}
|
|
@end example
|
|
|
|
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 @emph{is} handled by libltdl however, and it is important
|
|
to ensure the @code{dlloader_exit} callback releases any resources claimed
|
|
during the initialisation phase.
|
|
|
|
@page
|
|
@noindent
|
|
libltdl provides the following functions for writing your own module
|
|
loaders:
|
|
|
|
@deftypefun int lt_dlloader_add (@w{lt_dlloader_t *@var{place},} @w{lt_user_dlloader *@var{dlloader},} @w{const char *@var{loader_name}})
|
|
Add a new module loader to the list of all loaders, either as the
|
|
last loader (if @var{place} is @code{NULL}), else immediately before the
|
|
loader passed as @var{place}. @var{loader_name} will be returned by
|
|
@code{lt_dlloader_name} if it is subsequently passed a newly
|
|
registered loader. These @var{loader_name}s must be unique, or
|
|
@code{lt_dlloader_remove} and @code{lt_dlloader_find} cannot
|
|
work. Returns 0 for success.
|
|
|
|
@example
|
|
@{
|
|
/* Make myloader be the last one. */
|
|
if (lt_dlloader_add (NULL, myloader) != 0)
|
|
perror (lt_dlerror ());
|
|
@}
|
|
@end example
|
|
@end deftypefun
|
|
|
|
@deftypefun int lt_dlloader_remove (@w{const char *@var{loader_name}})
|
|
Remove the loader identified by the unique name, @var{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 @code{lt_dlerror}.
|
|
|
|
@example
|
|
@{
|
|
/* Remove myloader. */
|
|
if (lt_dlloader_remove ("myloader") != 0)
|
|
perror (lt_dlerror ());
|
|
@}
|
|
@end example
|
|
@end deftypefun
|
|
|
|
@deftypefun {lt_dlloader_t *}lt_dlloader_next (@w{lt_dlloader_t *@var{place}})
|
|
Iterate over the module loaders, returning the first loader if @var{place} is
|
|
@code{NULL}, and the next one on subsequent calls. The handle is for use with
|
|
@code{lt_dlloader_add}.
|
|
|
|
@example
|
|
@{
|
|
/* Make myloader be the first one. */
|
|
if (lt_dlloader_add (lt_dlloader_next (NULL), myloader) != 0)
|
|
return ERROR;
|
|
@}
|
|
@end example
|
|
@end deftypefun
|
|
|
|
@deftypefun {lt_dlloader_t *}lt_dlloader_find (@w{const char *@var{loader_name}})
|
|
Return the first loader with a matching @var{loader_name} identifier, or else
|
|
@code{NULL}, if the identifier is not found.
|
|
|
|
The identifiers which may be used by libltdl itself, if the host
|
|
architecture supports them are @dfn{dlopen}@footnote{This is used for
|
|
the host dependent module loading @sc{api} -- @code{shl_load} and
|
|
@code{LoadLibrary} for example}, @dfn{dld} and @dfn{dlpreload}.
|
|
|
|
@example
|
|
@{
|
|
/* 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;
|
|
@}
|
|
@end example
|
|
@end deftypefun
|
|
|
|
@deftypefun {const char *}lt_dlloader_name (@w{lt_dlloader_t *@var{place}})
|
|
Return the identifying name of @var{PLACE}, as obtained from
|
|
@code{lt_dlloader_next} or @code{lt_dlloader_find}. If this function fails,
|
|
it will return @code{NULL} and set an error for retrieval with
|
|
@code{lt_dlerror}.
|
|
@end deftypefun
|
|
|
|
@deftypefun {lt_dlloader_data_t *}lt_dlloader_data (@w{lt_dlloader_t *@var{place}})
|
|
Return the address of the @code{dlloader_data} of @var{PLACE}, as
|
|
obtained from @code{lt_dlloader_next} or @code{lt_dlloader_find}. If
|
|
this function fails, it will return @code{NULL} and set an error for
|
|
retrieval with @code{lt_dlerror}.
|
|
@end deftypefun
|
|
|
|
@subsection Error handling within user module loaders
|
|
|
|
@deftypefun int lt_dladderror (@w{const char *@var{diagnostic}})
|
|
This function allows you to integrate your own error messages into
|
|
@code{lt_dlerror}. Pass in a suitable diagnostic message for return by
|
|
@code{lt_dlerror}, and an error identifier for use with
|
|
@code{lt_dlseterror} is returned.
|
|
|
|
If the allocation of an identifier fails, this function returns -1.
|
|
|
|
@example
|
|
int myerror = lt_dladderror ("Doh!");
|
|
if (myerror < 0)
|
|
perror (lt_dlerror ());
|
|
@end example
|
|
@end deftypefun
|
|
|
|
@deftypefun int lt_dlseterror (@w{int @var{errorcode}})
|
|
When writing your own module loaders, you should use this function to
|
|
raise errors so that they are propogated through the @code{lt_dlerror}
|
|
interface. All of the standard errors used by libltdl are declared in
|
|
@file{ltdl.h}, or you can add more of your own with
|
|
@code{lt_dladderror}. This function returns 0 on success.
|
|
|
|
@example
|
|
if (lt_dlseterror (LTDL_ERROR_NO_MEMORY) != 0)
|
|
perror (lt_dlerror ());
|
|
@end example
|
|
@end deftypefun
|
|
|
|
@node Other languages
|
|
@chapter Using libtool with other languages
|
|
@cindex C, not using
|
|
@cindex languages, non-C
|
|
@cindex C++, using
|
|
|
|
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::
|
|
@end menu
|
|
|
|
@node C++ libraries
|
|
@section Writing libraries for C++
|
|
@c FIXME: in the TOC, the ++ is too large (seems to be math mode)
|
|
@cindex trouble with C++
|
|
@cindex pitfalls using C++
|
|
@cindex C++, pitfalls
|
|
|
|
Creating libraries of C++ code should be a fairly straightforward
|
|
process, because its object files differ from C ones in only three ways:
|
|
|
|
@enumerate 1
|
|
@item
|
|
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.
|
|
|
|
@item
|
|
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 @file{ld} directly to link such libraries, and
|
|
we should use the C++ compiler instead.
|
|
|
|
@item
|
|
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 @file{ld} to link a C++ program or library is deemed
|
|
to fail. However, running the C++ compiler directly may lead to
|
|
problems related with inter-library dependencies.
|
|
@end enumerate
|
|
|
|
The conclusion is that libtool is not ready for general use for C++
|
|
libraries. You should avoid any global or static variable
|
|
initializations that would cause an ``initializer element is not
|
|
constant'' error if you compiled them with a standard C compiler.
|
|
|
|
There are other ways of working around this problem, but they are beyond
|
|
the scope of this manual.
|
|
|
|
Furthermore, you'd better find out, at configure time, what are the C++
|
|
Standard libraries that the C++ compiler will link in by default, and
|
|
explicitly list them in the link command line. Hopefully, in the
|
|
future, libtool will be able to do this job by itself.
|
|
|
|
|
|
@node Troubleshooting
|
|
@chapter Troubleshooting
|
|
@cindex troubleshooting
|
|
@cindex problems, solving
|
|
@cindex solving problems
|
|
@cindex problems, blaming somebody else for
|
|
|
|
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.
|
|
@end menu
|
|
|
|
@node Libtool test suite
|
|
@section The libtool test suite
|
|
@cindex test suite
|
|
|
|
Libtool comes with its own set of programs 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 @file{INSTALL} file, you may run @kbd{make 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 test suite.
|
|
* When tests fail:: What to do when a test fails.
|
|
@end menu
|
|
|
|
@node Test descriptions
|
|
@subsection Description of test suite
|
|
|
|
Here is a list of the current programs in the test suite, and what they
|
|
test for:
|
|
|
|
@table @file
|
|
|
|
@item cdemo-conf.test
|
|
@itemx cdemo-exec.test
|
|
@itemx cdemo-make.test
|
|
@itemx cdemo-static.test
|
|
@itemx cdemo-shared.test
|
|
@pindex cdemo-conf.test
|
|
@pindex cdemo-exec.test
|
|
@pindex cdemo-make.test
|
|
@pindex cdemo-static.test
|
|
@pindex cdemo-shared.test
|
|
These programs check to see that the @file{cdemo} subdirectory of the
|
|
libtool distribution can be configured and built correctly.
|
|
|
|
The @file{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 @file{cdemo-make.test} and @file{cdemo-exec.test} are executed
|
|
three times, under three different libtool configurations:
|
|
@file{cdemo-conf.test} configures @file{cdemo/libtool} to build both
|
|
static and shared libraries (the default for platforms that support
|
|
both), @file{cdemo-static.test} builds only static libraries
|
|
(@samp{--disable-shared}), and @file{cdemo-shared.test} builds only
|
|
shared libraries (@samp{--disable-static}).
|
|
|
|
@item demo-conf.test
|
|
@itemx demo-exec.test
|
|
@itemx demo-inst.test
|
|
@itemx demo-make.test
|
|
@itemx demo-unst.test
|
|
@itemx demo-static.test
|
|
@itemx demo-shared.test
|
|
@itemx demo-nofast.test
|
|
@itemx demo-pic.test
|
|
@itemx demo-nopic.test
|
|
@pindex demo-conf.test
|
|
@pindex demo-exec.test
|
|
@pindex demo-inst.test
|
|
@pindex demo-make.test
|
|
@pindex demo-unst.test
|
|
@pindex demo-static.test
|
|
@pindex demo-shared.test
|
|
@pindex demo-nofast.test
|
|
@pindex demo-pic.test
|
|
@pindex demo-nopic.test
|
|
These programs check to see that the @file{demo} subdirectory of the
|
|
libtool distribution can be configured, built, installed, and
|
|
uninstalled correctly.
|
|
|
|
The @file{demo} subdirectory contains a demonstration of a trivial
|
|
package that uses libtool. The tests @file{demo-make.test},
|
|
@file{demo-exec.test}, @file{demo-inst.test} and
|
|
@file{demo-unst.test} are executed four times, under four different
|
|
libtool configurations: @file{demo-conf.test} configures
|
|
@file{demo/libtool} to build both static and shared libraries,
|
|
@file{demo-static.test} builds only static libraries
|
|
(@samp{--disable-shared}), and @file{demo-shared.test} builds only
|
|
shared libraries (@samp{--disable-static}).
|
|
@file{demo-nofast.test} configures @file{demo/libtool} to
|
|
disable the fast-install mode (@samp{--enable-fast-install=no}).
|
|
@file{demo-pic.test} configures @file{demo/libtool} to
|
|
prefer building PIC code (@samp{--with-pic}), @file{demo-nopic.test}
|
|
to prefer non-PIC code (@samp{--without-pic}).
|
|
|
|
@item deplibs.test
|
|
@pindex deplibs.test
|
|
Many systems cannot link static libraries into shared libraries.
|
|
libtool uses a @code{deplibs_check_method} to prevent such cases.
|
|
This tests checks whether libtool's @code{deplibs_check_method}
|
|
works properly.
|
|
|
|
@item hardcode.test
|
|
@pindex hardcode.test
|
|
On all systems with shared libraries, the location of the library can be
|
|
encoded in executables that are linked against it @pxref{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.
|
|
|
|
@item build-relink.test
|
|
@pindex build-relink.test
|
|
Checks whether variable @var{shlibpath_overrides_runpath} is properly
|
|
set. If the test fails and @var{VERBOSE} is set, it will indicate what
|
|
the variable should have been set to.
|
|
|
|
@item noinst-link.test
|
|
@pindex 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.
|
|
|
|
@item depdemo-conf.test
|
|
@itemx depdemo-exec.test
|
|
@itemx depdemo-inst.test
|
|
@itemx depdemo-make.test
|
|
@itemx depdemo-unst.test
|
|
@itemx depdemo-static.test
|
|
@itemx depdemo-shared.test
|
|
@itemx depdemo-nofast.test
|
|
@pindex depdemo-conf.test
|
|
@pindex depdemo-exec.test
|
|
@pindex depdemo-inst.test
|
|
@pindex depdemo-make.test
|
|
@pindex depdemo-unst.test
|
|
@pindex depdemo-static.test
|
|
@pindex depdemo-shared.test
|
|
@pindex depdemo-nofast.test
|
|
These programs check to see that the @file{depdemo} subdirectory of the
|
|
libtool distribution can be configured, built, installed, and
|
|
uninstalled correctly.
|
|
|
|
The @file{depdemo} subdirectory contains a demonstration of inter-library
|
|
dependencies with libtool. The test programs link some interdependent
|
|
libraries.
|
|
|
|
The tests @file{depdemo-make.test}, @file{depdemo-exec.test},
|
|
@file{depdemo-inst.test} and @file{depdemo-unst.test} are executed
|
|
four times, under four different libtool configurations:
|
|
@file{depdemo-conf.test} configures @file{depdemo/libtool} to build both
|
|
static and shared libraries, @file{depdemo-static.test} builds only static
|
|
libraries (@samp{--disable-shared}), and @file{depdemo-shared.test} builds
|
|
only shared libraries (@samp{--disable-static}).
|
|
@file{depdemo-nofast.test} configures @file{depdemo/libtool} to
|
|
disable the fast-install mode (@samp{--enable-fast-install=no}.
|
|
|
|
@item mdemo-conf.test
|
|
@itemx mdemo-exec.test
|
|
@itemx mdemo-inst.test
|
|
@itemx mdemo-make.test
|
|
@itemx mdemo-unst.test
|
|
@itemx mdemo-static.test
|
|
@itemx mdemo-shared.test
|
|
@pindex mdemo-conf.test
|
|
@pindex mdemo-exec.test
|
|
@pindex mdemo-inst.test
|
|
@pindex mdemo-make.test
|
|
@pindex mdemo-unst.test
|
|
@pindex mdemo-static.test
|
|
@pindex mdemo-shared.test
|
|
These programs check to see that the @file{mdemo} subdirectory of the
|
|
libtool distribution can be configured, built, installed, and
|
|
uninstalled correctly.
|
|
|
|
The @file{mdemo} subdirectory contains a demonstration of a package that
|
|
uses libtool and the system independent dlopen wrapper @file{libltdl} to
|
|
load modules. The library @file{libltdl} provides a dlopen wrapper for
|
|
various platforms (Linux, Solaris, HP/UX etc.) including support for
|
|
dlpreopened modules (@pxref{Dlpreopening}).
|
|
|
|
The tests @file{mdemo-make.test}, @file{mdemo-exec.test},
|
|
@file{mdemo-inst.test} and @file{mdemo-unst.test} are executed
|
|
three times, under three different libtool configurations:
|
|
@file{mdemo-conf.test} configures @file{mdemo/libtool} to build both
|
|
static and shared libraries, @file{mdemo-static.test} builds only static
|
|
libraries (@samp{--disable-shared}), and @file{mdemo-shared.test} builds
|
|
only shared libraries (@samp{--disable-static}).
|
|
|
|
@item dryrun.test
|
|
@pindex dryrun.test
|
|
This test checks whether libtool's @code{--dry-run} mode works properly.
|
|
|
|
@item assign.test
|
|
@pindex assign.test
|
|
Checks whether we don't put break or continue on the same
|
|
line as an assignment in the libtool script.
|
|
|
|
@item link.test
|
|
@pindex link.test
|
|
This test guarantees that linking directly against a non-libtool static
|
|
library works properly.
|
|
|
|
@item link-2.test
|
|
@pindex link-2.test
|
|
This test makes sure that files ending in @samp{.lo} are never linked
|
|
directly into a program file.
|
|
|
|
@item nomode.test
|
|
@pindex nomode.test
|
|
Check whether we can actually get help for libtool.
|
|
|
|
@item quote.test
|
|
@pindex quote.test
|
|
This program checks libtool's metacharacter quoting.
|
|
|
|
@item sh.test
|
|
@pindex sh.test
|
|
Checks whether a `test' command was forgotten in libtool.
|
|
|
|
@item suffix.test
|
|
@pindex suffix.test
|
|
When other programming languages are used with libtool (@pxref{Other
|
|
languages}), the source files may end in suffixes other than @samp{.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.
|
|
|
|
@end table
|
|
|
|
@node When tests fail
|
|
@subsection When tests fail
|
|
@cindex failed tests
|
|
@cindex tests, failed
|
|
|
|
Each of the above tests are designed to produce no output when they are
|
|
run via @kbd{make check}. The exit status of each program tells the
|
|
@file{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 which may be useful in determining what the problem is.
|
|
|
|
Another way to have the test programs produce output is to set the
|
|
@var{VERBOSE} environment variable to @samp{yes} before running them.
|
|
For example, @kbd{env VERBOSE=yes make check} runs all the tests, and
|
|
has each of them display debugging information.
|
|
|
|
@node Reporting bugs
|
|
@section Reporting bugs
|
|
@cindex bug reports
|
|
@cindex reporting bugs
|
|
@cindex problem reports
|
|
|
|
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 (@pxref{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 (@pxref{Bugs, ,
|
|
Reporting Bugs, emacs, The Emacs Manual}). 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 @value{BUGADDR} with any appropriate
|
|
@emph{facts}, such as test suite output (@pxref{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 @kbd{ltconfig --version}).
|
|
|
|
@node Maintaining
|
|
@chapter 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.
|
|
@end menu
|
|
|
|
@node New ports
|
|
@section Porting libtool to new systems
|
|
|
|
Before you embark on porting libtool to an unsupported system, it is
|
|
worthwhile to send e-mail to @value{MAILLIST}, 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
|
|
@end menu
|
|
|
|
@node Information sources
|
|
@subsection Information sources
|
|
|
|
Once it is clear that a new port is necessary, you'll generally need the
|
|
following information:
|
|
|
|
@table @asis
|
|
@item canonical system name
|
|
You need the output of @code{config.guess} for this system, so that you
|
|
can make changes to the libtool configuration process without affecting
|
|
other systems.
|
|
|
|
@item man pages for @code{ld} and @code{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.
|
|
|
|
@item man pages for @code{ld.so}, @code{rtld}, or equivalent
|
|
These are a valuable resource for understanding how shared libraries are
|
|
loaded on the system.
|
|
|
|
@item man page for @code{ldconfig}, or equivalent
|
|
This page usually describes how to install shared libraries.
|
|
|
|
@item output from @kbd{ls -l /lib /usr/lib}
|
|
This shows the naming convention for shared libraries on the system,
|
|
including which names should be symbolic links.
|
|
|
|
@item any additional documentation
|
|
Some systems have special documentation on how to build and install
|
|
shared libraries.
|
|
@end table
|
|
|
|
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
|
|
@code{libtool.m4} macros in order to make platform-specific changes to
|
|
the configuration process. You should search that file for the
|
|
@code{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 (@pxref{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 @code{ltmain.in} script accordingly. Be sure to write to the
|
|
mailing list before you make changes to @code{ltmain.in}, since they may
|
|
have advice on the most effective way of accomplishing what you want.
|
|
|
|
@node Porting inter-library dependencies
|
|
@subsection Porting inter-library dependencies support
|
|
@cindex inter-library dependency
|
|
@vindex deplibs_check_method
|
|
|
|
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 @email{badger@@prtr-13.ucsc.edu}. Here's a shortened version
|
|
of the message that contained his patch:
|
|
|
|
The basic architecture is this: in @file{libtool.m4}, the person who
|
|
writes libtool makes sure @samp{$deplibs} is included in
|
|
@samp{$archive_cmds} somewhere and also sets the variable
|
|
@samp{$deplibs_check_method}, and maybe @samp{$file_magic_cmd} when
|
|
@samp{deplibs_check_method} is file_magic.
|
|
|
|
@samp{deplibs_check_method} can be one of five things:
|
|
@table @samp
|
|
@item file_magic [@var{regex}]
|
|
@vindex file_magic
|
|
@vindex file_magic_cmd
|
|
@vindex file_magic_test_file
|
|
looks in the library link path for libraries that have the right
|
|
libname. Then it runs @samp{$file_magic_cmd} on the library and checks
|
|
for a match against @var{regex} using @code{egrep}. When
|
|
@var{file_magic_test_file} is set by @file{libtool.m4}, it is used as an
|
|
argument to @samp{$file_magic_cmd} in order to verify whether the
|
|
regular expression matches its output, and warn the user otherwise.
|
|
|
|
@item test_compile
|
|
@vindex 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
|
|
@code{ldd}. It is currently unused, and will probably be dropped in the
|
|
future.
|
|
|
|
@item pass_all
|
|
@vindex 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.
|
|
|
|
@item none
|
|
@vindex none
|
|
It causes deplibs to be reassigned deplibs="". That way
|
|
@samp{archive_cmds} can contain deplibs on all platforms, but not have
|
|
deplibs used unless needed.
|
|
|
|
@item unknown
|
|
@vindex unknown
|
|
is the default for all systems unless overridden in @file{libtool.m4}.
|
|
It is the same as @samp{none}, but it documents that we really don't
|
|
know what the correct value should be, and we welcome patches that
|
|
improve it.
|
|
@end table
|
|
|
|
Then in @file{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
|
|
which method 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.
|
|
|
|
@node Tested platforms
|
|
@section Tested platforms
|
|
|
|
This table describes when libtool was last known to be tested on
|
|
platforms where it claims to support shared libraries:
|
|
|
|
@example
|
|
@include PLATFORMS
|
|
@end example
|
|
|
|
Note: The vendor-distributed HP-UX @code{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
|
|
@code{sed} (such as GNU @code{sed}) on these systems.
|
|
|
|
Note: The vendor-distributed NCR MP-RAS @code{cc} programs emits
|
|
copyright on standard error that confuse tests on size of
|
|
@file{conftest.err}. The workaround is to specify @code{CC}
|
|
when run @code{configure} with @kbd{CC='cc -Hnocopyr'}.
|
|
|
|
@node Platform quirks
|
|
@section 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.
|
|
* Archivers:: Programs that create static archives.
|
|
@end menu
|
|
|
|
@node References
|
|
@subsection References
|
|
|
|
The following is a list of valuable documentation references:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
SGI's IRIX Manual Pages, which can be found at
|
|
@url{http://techpubs.sgi.com/cgi-bin/infosrch.cgi?cmd=browse&db=man}.
|
|
|
|
@item
|
|
Sun's free service area
|
|
(@url{http://www.sun.com/service/online/free.html}) and documentation
|
|
server (@url{http://docs.sun.com/}).
|
|
@end itemize
|
|
|
|
@node Compilers
|
|
@subsection 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:
|
|
|
|
@table @code
|
|
@item 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 @samp{-fpic} or @samp{-fPIC} flags can be used to generate
|
|
position-independent code. @samp{-fPIC} is guaranteed to generate
|
|
working code, but the code is slower on m68k, m88k, and Sparc chips.
|
|
However, using @samp{-fpic} on those chips imposes arbitrary size limits
|
|
on the shared libraries.
|
|
@end table
|
|
|
|
The rest of this subsection lists compilers by the operating system that
|
|
they are bundled with:
|
|
|
|
@c FIXME these should all be better-documented
|
|
|
|
@table @code
|
|
@item aix3*
|
|
@itemx aix4*
|
|
AIX compilers have no PIC flags, since AIX has been ported only to
|
|
PowerPC and RS/6000 chips. @footnote{All code compiled for the PowerPC
|
|
and RS/6000 chips (@code{powerpc-*-*}, @code{powerpcle-*-*}, and
|
|
@code{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.}
|
|
|
|
@item hpux10*
|
|
Use @samp{+Z} to generate PIC.
|
|
|
|
@item osf3*
|
|
Digital/UNIX 3.x does not have PIC flags, at least not on the PowerPC
|
|
platform.
|
|
|
|
@item solaris2*
|
|
Use @samp{-KPIC} to generate PIC.
|
|
|
|
@item sunos4*
|
|
Use @samp{-PIC} to generate PIC.
|
|
@end table
|
|
|
|
@node Reloadable objects
|
|
@subsection Reloadable objects
|
|
|
|
On all known systems, a reloadable object can be created by running
|
|
@kbd{ld -r -o @var{output}.o @var{input1}.o @var{input2}.o}. This
|
|
reloadable object may be treated as exactly equivalent to other
|
|
objects.
|
|
|
|
@node Archivers
|
|
@subsection Archivers
|
|
|
|
On all known systems, building a static library can be accomplished by
|
|
running @kbd{ar cru lib@var{name}.a @var{obj1}.o @var{obj2}.o @dots{}},
|
|
where the @samp{.a} file is the output library, and each @samp{.o} file is an
|
|
object file.
|
|
|
|
On all known systems, if there is a program named @code{ranlib}, then it
|
|
must be used to ``bless'' the created library before linking against it,
|
|
with the @kbd{ranlib lib@var{name}.a} command. Some systems, like Irix,
|
|
use the @code{ar ts} command, instead.
|
|
|
|
@node libtool script contents
|
|
@section @code{libtool} script contents
|
|
@cindex implementation of libtool
|
|
@cindex libtool implementation
|
|
|
|
Since version 1.4, the @code{libtool} script is generated by
|
|
@code{configure} (@pxref{Configuring}). In earlier versions,
|
|
@code{configure} achieved this by calling a helper script called
|
|
@file{ltconfig}. From libtool version 0.7 to 1.0, this script
|
|
simply set shell variables, then sourced the libtool backend,
|
|
@code{ltmain.sh}. @code{ltconfig} from libtool version 1.1 through 1.3
|
|
inlined the contents of @code{ltmain.sh} into the generated
|
|
@code{libtool}, which improved performance on many systems. The tests
|
|
that @file{ltconfig} used to perform are now kept in @file{libtool.m4}
|
|
where thay can be written using Autoconf. This has the runtime
|
|
performance benefits of inlined @code{ltmain.sh}, @emph{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 which hold shell commands for
|
|
delayed evaluation, is to use the suffix @code{_cmd} where a single
|
|
line of valid shell script is needed, and the suffix @code{_cmds} where
|
|
multiple lines of shell script @strong{may} be delayed for later
|
|
evaluation. By convention, @code{_cmds} variables delimit the
|
|
evaluation units with the @code{~} character where necessary.
|
|
|
|
Here is a listing of each of the configuration variables, and how they
|
|
are used within @code{ltmain.sh} (@pxref{Configuring}):
|
|
|
|
@defvar AR
|
|
The name of the system library archiver.
|
|
@end defvar
|
|
|
|
@defvar CC
|
|
The name of the C compiler used to configure libtool.
|
|
@end defvar
|
|
|
|
@defvar LD
|
|
The name of the linker that libtool should use internally for reloadable
|
|
linking and possibly shared libraries.
|
|
@end defvar
|
|
|
|
@defvar NM
|
|
The name of a BSD-compatible @code{nm} program, which produces listings
|
|
of global symbols in one the following formats:
|
|
|
|
@example
|
|
@var{address} C @var{global-variable-name}
|
|
@var{address} D @var{global-variable-name}
|
|
@var{address} T @var{global-function-name}
|
|
@end example
|
|
@end defvar
|
|
|
|
@defvar RANLIB
|
|
Set to the name of the ranlib program, if any.
|
|
@end defvar
|
|
|
|
@defvar allow_undefined_flag
|
|
The flag that is used by @samp{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 @samp{unsupported} if there
|
|
is no way to generate a shared library with references to symbols that
|
|
aren't defined in that library.
|
|
@end defvar
|
|
|
|
@defvar always_export_symbols
|
|
Whether libtool should automatically generate a list of exported symbols
|
|
using @var{export_symbols_cmds} before linking an archive.
|
|
Set to @samp{yes} or @samp{no}. Default is @samp{no}.
|
|
@end defvar
|
|
|
|
@defvar archive_cmds
|
|
@defvarx archive_expsym_cmds
|
|
@defvarx old_archive_cmds
|
|
Commands used to create shared libraries, shared libraries with
|
|
@samp{-export-symbols} and static libraries, respectively.
|
|
@end defvar
|
|
|
|
@defvar old_archive_from_new_cmds
|
|
If the shared library depends on a static library,
|
|
@samp{old_archive_from_new_cmds} contains the commands used to create that
|
|
static library. If this variable is not empty, @samp{old_archive_cmds} is
|
|
not used.
|
|
@end defvar
|
|
|
|
@defvar 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, @samp{old_archive_from_expsyms_cmds}
|
|
contains the commands needed to create that static library. When these
|
|
commands are executed, the variable @var{soname} contains the name of the
|
|
shared library in question, and the @var{$objdir/$newlib} contains the
|
|
path of the static library these commands should build. After executing
|
|
these commands, libtool will proceed to link against @var{$objdir/$newlib}
|
|
instead of @var{soname}.
|
|
@end defvar
|
|
|
|
@defvar build_libtool_libs
|
|
Whether libtool should build shared libraries on this system. Set to
|
|
@samp{yes} or @samp{no}.
|
|
@end defvar
|
|
|
|
@defvar build_old_libs
|
|
Whether libtool should build static libraries on this system. Set to
|
|
@samp{yes} or @samp{no}.
|
|
@end defvar
|
|
|
|
@defvar compiler_c_o
|
|
Whether the compiler supports the @code{-c} and @code{-o} options
|
|
simultaneously. Set to @samp{yes} or @samp{no}.
|
|
@end defvar
|
|
|
|
@defvar compiler_o_lo
|
|
Whether the compiler supports compiling directly to a ".lo" file,
|
|
i.e whether object files do not have to have the suffix ".o".
|
|
Set to @samp{yes} or @samp{no}.
|
|
@end defvar
|
|
|
|
@defvar dlopen_support
|
|
Whether @code{dlopen} is supported on the platform.
|
|
Set to @samp{yes} or @samp{no}.
|
|
@end defvar
|
|
|
|
@defvar dlopen_self
|
|
Whether it is possible to @code{dlopen} the executable itself.
|
|
Set to @samp{yes} or @samp{no}.
|
|
@end defvar
|
|
|
|
@defvar dlopen_self_static
|
|
Whether it is possible to @code{dlopen} the executable itself, when it
|
|
is linked statically (@samp{-all-static}). Set to @samp{yes} or
|
|
@samp{no}.
|
|
@end defvar
|
|
|
|
@defvar echo
|
|
An @code{echo} program which does not interpret backslashes as an
|
|
escape character.
|
|
@end defvar
|
|
|
|
@defvar exclude_expsyms
|
|
List of symbols that should not be listed in the preloaded symbols.
|
|
@end defvar
|
|
|
|
@defvar export_dynamic_flag_spec
|
|
Compiler link flag that allows a dlopened shared library to reference
|
|
symbols that are defined in the program.
|
|
@end defvar
|
|
|
|
@defvar export_symbols_cmds
|
|
Commands to extract exported symbols from @var{libobjs} to the
|
|
file @var{export_symbols}.
|
|
@end defvar
|
|
|
|
@defvar extract_expsyms_cmds
|
|
Commands to extract the exported symbols list from a shared library.
|
|
These commands are executed if there is no file @var{$objdir/$soname-def},
|
|
and should write the names of the exported symbols to that file, for
|
|
the use of @samp{old_archive_from_expsyms_cmds}.
|
|
@end defvar
|
|
|
|
@defvar 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 in which @var{shlibpath_overrides_runpath} is
|
|
not @samp{yes}, so @var{fast_install} will be set to @samp{needless} in
|
|
this case. If @var{fast_install} set to @samp{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 @samp{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
|
|
@samp{yes} or @samp{needless}, depending on platform and configuration
|
|
flags, and it can be turned from @samp{yes} to @samp{no} with the
|
|
configure flag @samp{--disable-fast-install}.
|
|
@end defvar
|
|
|
|
@defvar finish_cmds
|
|
Commands to tell the dynamic linker how to find shared libraries in a
|
|
specific directory.
|
|
@end defvar
|
|
|
|
@defvar finish_eval
|
|
Same as @var{finish_cmds}, except the commands are not displayed.
|
|
@end defvar
|
|
|
|
@defvar fix_srcfile_path
|
|
Expression to fix the shell variable $srcfile for the compiler.
|
|
@end defvar
|
|
|
|
@defvar global_symbol_pipe
|
|
A pipeline that takes the output of @var{NM}, and produces a listing of
|
|
raw symbols followed by their C names. For example:
|
|
|
|
@example
|
|
$ @kbd{eval "$NM progname | $global_symbol_pipe"}
|
|
D @var{symbol1} @var{C-symbol1}
|
|
T @var{symbol2} @var{C-symbol2}
|
|
C @var{symbol3} @var{C-symbol3}
|
|
@dots{}
|
|
$
|
|
@end example
|
|
|
|
The first column contains the symbol type (used to tell data from code
|
|
on some platforms), but its meaning is system dependent.
|
|
@end defvar
|
|
|
|
@defvar global_symbol_to_cdecl
|
|
A pipeline that translates the output of @var{global_symbol_pipe} into
|
|
proper C declarations. On platforms whose linkers differentiate code
|
|
from data, such as HP/UX, data symbols will be declared as such, and
|
|
code symbols will be declared as functions. On platforms that don't
|
|
care, everything is assumed to be data.
|
|
@end defvar
|
|
|
|
@defvar hardcode_action
|
|
Either @samp{immediate} or @samp{relink}, depending on whether shared
|
|
library paths can be hardcoded into executables before they are installed,
|
|
or if they need to be relinked.
|
|
@end defvar
|
|
|
|
@defvar hardcode_direct
|
|
Set to @samp{yes} or @samp{no}, depending on whether the linker
|
|
hardcodes directories if a library is directly specified on the command
|
|
line (such as @samp{@var{dir}/lib@var{name}.a}) when
|
|
@var{hardcode_libdir_flag_spec} is specified.
|
|
@end defvar
|
|
|
|
@defvar 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 @samp{yes} or @samp{no}.
|
|
@end defvar
|
|
|
|
@defvar hardcode_libdir_flag_spec
|
|
Flag to hardcode a @var{libdir} variable into a binary, so that the
|
|
dynamic linker searches @var{libdir} for shared libraries at runtime.
|
|
If it is empty, libtool will try to use some other hardcoding mechanism.
|
|
@end defvar
|
|
|
|
@defvar hardcode_libdir_separator
|
|
If the compiler only accepts a single @var{hardcode_libdir_flag}, then
|
|
this variable contains the string that should separate multiple
|
|
arguments to that flag.
|
|
@end defvar
|
|
|
|
@defvar hardcode_minus_L
|
|
Set to @samp{yes} or @samp{no}, depending on whether the linker
|
|
hardcodes directories specified by @samp{-L} flags into the resulting
|
|
executable when @var{hardcode_libdir_flag_spec} is specified.
|
|
@end defvar
|
|
|
|
@defvar hardcode_shlibpath_var
|
|
Set to @samp{yes} or @samp{no}, depending on whether the linker
|
|
hardcodes directories by writing the contents of @samp{$shlibpath_var}
|
|
into the resulting executable when @var{hardcode_libdir_flag_spec} is
|
|
specified. Set to @samp{unsupported} if directories specified by
|
|
@samp{$shlibpath_var} are searched at run time, but not at link time.
|
|
@end defvar
|
|
|
|
@defvar host
|
|
@defvarx host_alias
|
|
For information purposes, set to the specified and canonical names of
|
|
the system that libtool was configured for.
|
|
@end defvar
|
|
|
|
@defvar include_expsyms
|
|
List of symbols that must always be exported when using @var{export_symbols}.
|
|
@end defvar
|
|
|
|
@defvar libext
|
|
The standard old archive suffix (normally "a").
|
|
@end defvar
|
|
|
|
@defvar libname_spec
|
|
The format of a library name prefix. On all Unix systems, static
|
|
libraries are called @samp{lib@var{name}.a}, but on some systems (such
|
|
as OS/2 or MS-DOS), the library is just called @samp{@var{name}.a}.
|
|
@end defvar
|
|
|
|
@defvar 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 @samp{-l@var{name}}.
|
|
@end defvar
|
|
|
|
@defvar link_all_deplibs
|
|
Whether libtool must link a program against all its dependency libraries.
|
|
Set to @samp{yes} or @samp{no}. Default is @samp{unknown}, which is
|
|
a synonym for @samp{yes}.
|
|
@end defvar
|
|
|
|
@defvar link_static_flag
|
|
Linker flag (passed through the C compiler) used to prevent dynamic
|
|
linking.
|
|
@end defvar
|
|
|
|
@defvar need_lib_prefix
|
|
Whether libtool should automatically prefix module names with 'lib'.
|
|
Set to @samp{yes} or @samp{no}. By default, it is @samp{unknown}, which
|
|
means the same as @samp{yes}, but documents that we are not really sure
|
|
about it.
|
|
@samp{yes} means that it is possible both to @code{dlopen} and to
|
|
link against a library without 'lib' prefix,
|
|
i.e. it requires @var{hardcode_direct} to be @samp{yes}.
|
|
@end defvar
|
|
|
|
@defvar need_version
|
|
Whether versioning is required for libraries, i.e. whether the
|
|
dynamic linker requires a version suffix for all libraries.
|
|
Set to @samp{yes} or @samp{no}. By default, it is @samp{unknown}, which
|
|
means the same as @samp{yes}, but documents that we are not really sure
|
|
about it.
|
|
@end defvar
|
|
|
|
@defvar need_locks
|
|
Whether files must be locked to prevent conflicts when compiling
|
|
simultaneously. Set to @samp{yes} or @samp{no}.
|
|
@end defvar
|
|
|
|
@defvar no_builtin_flag
|
|
Compiler flag to disable builtin functions that conflict with declaring
|
|
external global symbols as @code{char}.
|
|
@end defvar
|
|
|
|
@defvar no_undefined_flag
|
|
The flag that is used by @samp{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.
|
|
@end defvar
|
|
|
|
@defvar objdir
|
|
The name of the directory that contains temporary libtool files.
|
|
@end defvar
|
|
|
|
@defvar objext
|
|
The standard object file suffix (normally "o").
|
|
@end defvar
|
|
|
|
@defvar pic_flag
|
|
Any additional compiler flags for building library object files.
|
|
@end defvar
|
|
|
|
@defvar postinstall_cmds
|
|
@defvarx old_postinstall_cmds
|
|
Commands run after installing a shared or static library, respectively.
|
|
@end defvar
|
|
|
|
@defvar postuninstall_cmds
|
|
@defvarx old_postuninstall_cmds
|
|
Commands run after uninstalling a shared or static library, respectively.
|
|
@end defvar
|
|
|
|
@defvar reload_cmds
|
|
@defvarx reload_flag
|
|
Commands to create a reloadable object.
|
|
@end defvar
|
|
|
|
@defvar runpath_var
|
|
The environment variable that tells the linker which directories to
|
|
hardcode in the resulting executable.
|
|
@end defvar
|
|
|
|
@defvar 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
|
|
@code{fast_install}. The default value is @samp{unknown}, which is
|
|
equivalent to @samp{no}.
|
|
@end defvar
|
|
|
|
@defvar shlibpath_var
|
|
The environment variable that tells the dynamic linker where to find
|
|
shared libraries.
|
|
@end defvar
|
|
|
|
@defvar soname_spec
|
|
The name coded into shared libraries, if different from the real name of
|
|
the file.
|
|
@end defvar
|
|
|
|
@defvar striplib
|
|
@defvarx old_striplib
|
|
Command to strip a shared (@code{striplib}) or static (@code{old_striplib})
|
|
library, respectively. If these variables are empty, the strip flag
|
|
in the install mode will be ignored for libraries (@pxref{Install mode}).
|
|
@end defvar
|
|
|
|
@defvar 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.
|
|
@end defvar
|
|
|
|
@defvar 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
|
|
@var{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 @code{-L} also augment the search path.
|
|
@end defvar
|
|
|
|
@defvar thread_safe_flag_spec
|
|
Linker flag (passed through the C compiler) used to generate thread-safe
|
|
libraries.
|
|
@end defvar
|
|
|
|
@defvar version_type
|
|
The library version numbering type. One of @samp{libtool},
|
|
@samp{freebsd-aout}, @samp{freebsd-elf}, @samp{irix}, @samp{linux},
|
|
@samp{osf}, @samp{sunos}, @samp{windows}, or @samp{none}.
|
|
@end defvar
|
|
|
|
@defvar whole_archive_flag_spec
|
|
Compiler flag to generate shared objects from convenience archives.
|
|
@end defvar
|
|
|
|
@defvar wl
|
|
The C compiler flag that allows libtool to pass a flag directly to the
|
|
linker. Used as: @code{$@{wl@}@var{some-flag}}.
|
|
@end defvar
|
|
|
|
Variables ending in @samp{_cmds} or @samp{_eval} contain a
|
|
@samp{~}-separated list of commands that are @code{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 @samp{_spec} are @code{eval}ed before being used by
|
|
libtool.
|
|
|
|
@node Cheap tricks
|
|
@section Cheap tricks
|
|
|
|
Here are a few tricks that you can use in order to make maintainership
|
|
easier:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
When people report bugs, ask them to use the @samp{--config},
|
|
@samp{--debug}, or @samp{--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.
|
|
|
|
@item
|
|
Rather than reconfiguring libtool every time I make a change to
|
|
@code{ltmain.in}, I keep a permanent @code{libtool} script in my
|
|
@var{PATH}, which sources @code{ltmain.in} directly.
|
|
|
|
The following steps describe how to create such a script, where
|
|
@code{/home/src/libtool} is the directory containing the libtool source
|
|
tree, @code{/home/src/libtool/libtool} is a libtool script that has been
|
|
configured for your platform, and @code{~/bin} is a directory in your
|
|
@var{PATH}:
|
|
|
|
@example
|
|
trick$ cd ~/bin
|
|
trick$ sed '/^# 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@@) @@VERSION@@@@TIMESTAMP@@
|
|
trick$
|
|
@end example
|
|
@end itemize
|
|
|
|
The output of the final @samp{libtool --version} command shows that the
|
|
@code{ltmain.in} script is being used directly. Now, modify
|
|
@code{~/bin/libtool} or @code{/home/src/libtool/ltmain.in} directly in
|
|
order to test new changes without having to rerun @code{configure}.
|
|
|
|
@page
|
|
@node Index
|
|
@unnumbered Index
|
|
|
|
@printindex cp
|
|
|
|
@c summarycontents
|
|
@contents
|
|
@bye
|