mirror/libtool
2
0
Fork 0
mirror of git://git.savannah.gnu.org/libtool.git synced 2024-11-27 06:09:57 +08:00
Code Issues Packages Projects Releases Wiki Activity

*** empty log message ***

Browse Source
This commit is contained in:
Gordon Matzigkeit 1997-05-24 22:50:52 +00:00 committed by Gordon Matzigkeit
parent b24f92f4fe
commit 3245427f31
8 changed files with 341 additions and 281 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

15
ChangeLog
View File

@ -1,3 +1,18 @@
Sat May 10 12:21:58 1997 Gordon Matzigkeit <gord@gnu.ai.mit.edu>
* ltconfig.in: Trivial port to FreeBSD 3. From David Nugent.
Fri Apr 25 13:23:33 1997 Gordon Matzigkeit <gord@gnu.ai.mit.edu>
* ltmain.sh.in (link): Remove all traces of `-whole-archive',
`-no-whole-archive', and libtool convenience libraries. They were
more trouble than they're worth. If these are ever reimplemented,
they need more careful attention to make portable.
* libtool.m4, ltconfig.in: Added a `--disable-static' flag to turn
of static library creation. From Tom Lees (who finally convinced
me that it was the Right Thing to do).
Tue Apr 22 12:41:34 1997 Gordon Matzigkeit <gord@gnu.ai.mit.edu>
* ltmain.sh.in (hardcode_runpath_var, runpath_var): Use them, if

4
NEWS
View File

@ -4,11 +4,11 @@ New in 0.9e:
* Bug fixes.
* Automake support for Libtool now uses the LTLIBRARIES primary. See
the Automake documentation for more information.
* Added new `--disable-static' flag to disable building static
libraries on platforms that have shared libs.
* Basic support for dynamically loaded modules: new `-export-dynamic'
linking flag and corresponding `dlname' mode.
* New `--features' flag to display configured libtool attributes.
* Basic support for convenience libraries made of libtool objects: new
`-whole-archive' and `-no-whole-archive' linking flags.
* Support *-*-linux-gnu* as an alias for *-*-linux*.
* Support for *-*-openbsd*.

2
README
View File

@ -12,7 +12,7 @@ Shared library support has been implemented for these platforms:
AIX 3.x (*-*-aix3*)
AIX 4.x (*-*-aix4*)
Digital/UNIX 3.x, 4.x, a.k.a. OSF/1 (*-*-osf3*, *-*-osf4*)
FreeBSD 2.x (*-*-freebsd*)
FreeBSD 2.x, 3.x (*-*-freebsd2*, *-*-freebsd3*)
HP-UX 9.x, 10.x (*-*-hpux9*, *-*-hpux10*)
IRIX 5.x, 6.x (*-*-irix5*, *-*-irix6*)
Linux ELF targets (*-*-linux*, except *-*-linuxaout* and *-*-linuxoldld*)

73
TODO
View File

@ -1,41 +1,62 @@
* Sanity check to detect broken collect2 on AIX (see collect2bug).
Before 1.0:
***********
* Document inter-library dependencies, and allowing undefined
symbols (`-allow-undefined').
* Document inter-library dependencies, and write a flag to allow
undefined symbols (`-allow-undefined'). We'll need a special flag for
OSF/1 not to warn about this
(allow_undefined_flag='-expect_unresolved', inserted into
archive_cmds).
* Document convenience libraries, -whole-archive, and
-no-whole-archive.
* The way we'll implement `-allow-undefined' is to have link mode
search for `${allow_undefined_flag}' in the archive_cmds. If it finds
it, then either set allow_undefined_flag to empty, or leave it alone
(if -allow-undefined is specified). If it does not exist (such as on
AIX), then create a static library instead.
* Document the -export-dynamic flag, and the new dlname mode.
* Document the -export-dynamic flag, and the new dlname mode. These
should be discussed under a node called `Dynamic modules' or
something.
For 1.1:
After 1.0:
**********
* We also need a way to use convenience libraries just to resolve
symbols, rather than the (simplistic) whole-archive and
no-whole-archive.
* A better check to detect broken collect2 on AIX, once the bug is
fixed in GCC.
* Write libtool not to be dependent on the compiler used to configure
it.
* We could use libtool object convenience libraries that resolve
symbols to be included in a libtool archive.
* Implement full multi-language support. There are beginnings of this
in the manual (Other Languages).
* Finish up the dlname mode, and get it integrated with DLD. We need
a way for different major versions of the same .la to coexist. This
also involves writing a better uninstall mode, so that nothing
breaks.
Sometime in the future (maybe):
* Implement full multi-language support. Currently, this is only for
C++, but there are beginnings of this in the manual (Other Languages).
This includes writing libtool not to be so dependent on the compiler
used to configure it.
* Implement `-static' linking against installed libraries, even when
the OS does not have static system libraries. This would need to be
done by parsing `-L' and `-l', searching for libNAME.a manually, and
adding the full path to it.
Things to think about:
**********************
* Implement full support for other basic library types (libhello_g,
libhello_p). Make these types configurable. Some thinking will have
to be done about the defaults, and what libhello (standard type)
should be.
* Implement full support for other orthogonal library types
(libhello_g, libhello_p). Make these types configurable. Some
thinking will have to be done about the defaults, and what libhello
(standard type) should be.
Maybe we should just add an autoconf macro and get creative with
program_transform_name, or something. These changes should be
library_transform_name, or something. These changes should be
partially driven by the needs of packaging tools, such as RPM and
dpkg.
* Add support for windoze DLL's. Check out Lesstif and Tcl
configuration again. The Cygnus win32 project may also be of value.
* Talk with RMS about his so-called `automatic package generation
tool.' This is probably what Thomas has been murmuring about for the
Hurd. We'll need to integrate package-supplied programs such as
libtool into that scheme, since it manages some of the preinstall and
postinstall commands, but isn't installed itself. Probably, things
like libtool should be distributed as part of such a binary package.
* Add support for windoze DLL's, and maybe other jumptable libs.
Check out Lesstif and Tcl configuration again (maybe they would be
interested in libtool by now?). The Cygnus win32 project may also be
of value, though it still seems pretty rudimentary right now.

403
doc/libtool.texi
View File

@ -96,100 +96,102 @@ version @value{VERSION}.
@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.
* Libtool paradigm:: How libtool's view of libraries is different.
* Using libtool:: Example of using libtool to build libraries.
* Invoking libtool:: Running the @file{libtool} script.
* Integrating Libtool:: Using libtool in your own packages.
* Integrating libtool:: Using libtool in your own packages.
* Versioning:: Using library interface versions.
* Library Tips:: Tips for library interface design.
* Other Languages:: Using libtool without a C compiler.
* Library tips:: Tips for library interface design.
* Dlopened modules:: @code{dlopen}ing libtool-created libraries.
* 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.
* Other implementations:: How other people have solved these issues.
* Postmortem:: Learning from past difficulties.
Using Libtool
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.
* Installing Libraries:: Making libraries available to users.
* Installing Executables:: Making programs available to users.
* Static Libraries:: When shared libraries are not wanted.
* Creating object files:: Compiling object files for libraries.
* Linking libraries:: Creating libraries from object files.
* Linking executables:: Linking object files against libtool libraries.
* Installing libraries:: Making libraries available to users.
* Installing executables:: Making programs available to users.
* Static libraries:: When shared libraries are not wanted.
Invoking @file{libtool}
* Compile Mode:: Creating library object files.
* Link Mode:: Generating executables and libraries.
* Install Mode:: Making libraries and executables public.
* Finish Mode:: Completing a library installation.
* Uninstall Mode:: Removing executables and libraries.
* Compile mode:: Creating library object files.
* Link mode:: Generating executables and libraries.
* Dlname mode:: Obtaining a file to @code{dlopen(3)}.
* Install mode:: Making libraries and executables public.
* Finish mode:: Completing a library installation.
* Uninstall mode:: Removing executables and libraries.
Integrating Libtool with Your Own Packages
Integrating libtool with your own packages
* Makefile Rules:: Writing Makefile rules for libtool.
* Makefile rules:: Writing Makefile rules for libtool.
* Using Automake:: Automatically supporting libtool.
* Configuring:: Configuring libtool for a host system.
* Distributing:: What files to distribute with your package.
Configuring Libtool
Configuring libtool
* Invoking ltconfig:: @file{ltconfig} command line options.
* ltconfig Example:: Manually configuring a @file{libtool}.
* ltconfig example:: Manually configuring a @file{libtool}.
* AM_PROG_LIBTOOL:: Configuring @file{libtool} in @file{configure.in}.
Including Libtool with Your Package
Including libtool with your package
* Invoking libtoolize:: @file{libtoolize} command line options.
* Autoconf .o Macros:: Autoconf macros that set object file names.
* Autoconf .o macros:: Autoconf macros that set object file names.
Library Interface Versions
Library interface versions
* Interfaces:: What are library interfaces?
* Libtool Versioning:: Libtool's versioning system.
* Updating Version Info:: Changing version information before releases.
* Libtool versioning:: Libtool's versioning system.
* Updating version info:: Changing version information before releases.
Tips for Interface Design
Tips for interface design
* C Header Files:: How to write portable include files.
* C header files:: How to write portable include files.
Using Libtool with Other Languages
Using libtool with other languages
* C++ Libraries:: Using libtool with C++.
* C++ libraries::
Troubleshooting
* Libtool Test Suite:: Libtool's self-tests.
* Reporting Bugs:: How to report problems with libtool.
* Libtool test suite:: Libtool's self-tests.
* Reporting bugs:: How to report problems with libtool.
The Libtool Test Suite
The libtool test suite
* Test Descriptions:: The contents of the test suite.
* When Tests Fail:: What to do when a test fails.
* Test descriptions:: The contents of the test suite.
* When tests fail:: What to do when a test fails.
Maintainance Notes for Libtool
Maintainance 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.
* 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.
Platform Quirks
Platform quirks
* Compilers:: Creating object files from source files.
* Reloadable Objects:: Binding object files together.
* Reloadable objects:: Binding object files together.
* Archivers:: Programs that create static archives.
* Strip:: Removing unnecessary linkage information.
@end detailmenu
@end menu
@ -231,12 +233,12 @@ 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.
* Other implementations:: How other people have solved these issues.
* Postmortem:: Learning from past difficulties.
@end menu
@node Motivation
@section Motivation for Writing Libtool
@section Motivation for writing libtool
@cindex Motivation for writing libtool
@cindex Design philosophy
@ -274,7 +276,7 @@ Portability to other (non-GNU) architectures and tools is desirable.
@end enumerate
@node Issues
@section Implementation Issues
@section Implementation issues
@cindex Tricky design issues
@cindex Design issues
@ -316,8 +318,8 @@ The install Makefile target should warn the user to set
required.
@end enumerate
@node Other Implementations
@section Other Implementations
@node Other implementations
@section Other implementations
I have investigated several different implementations of building shared
libraries as part of a freeware package. At first, I made notes on the
@ -328,7 +330,7 @@ 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
@section A postmortem analysis of other implementations
@cindex Other implementations, flaws in
@cindex Reuseability of library systems
@ -362,8 +364,8 @@ I hope that libtool will be useful to and used by the GNU community, and
that the lessons I've learned in writing it will be taken up and
implemented by designers of library systems.
@node Libtool Paradigm
@chapter The Libtool Paradigm
@node Libtool paradigm
@chapter The libtool paradigm
At first, libtool was designed to support an arbitrary number of library
object types. After porting libtool to more platforms, the author
@ -384,8 +386,8 @@ 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 gets simpler.
@node Using Libtool
@chapter Using Libtool
@node Using libtool
@chapter Using libtool
@cindex Examples of using libtool
@cindex Libtool examples
@ -427,16 +429,16 @@ 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.
* Installing Libraries:: Making libraries available to users.
* Installing Executables:: Making programs available to users.
* Static Libraries:: When shared libraries are not wanted.
* Creating object files:: Compiling object files for libraries.
* Linking libraries:: Creating libraries from object files.
* Linking executables:: Linking object files against libtool libraries.
* 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
@node Creating object files
@section Creating object files
@cindex Compiling object files
@cindex Object files, compiling
@ -512,8 +514,8 @@ gcc -g -O -c hello.c
burger$
@end example
@node Linking Libraries
@section Linking Libraries
@node Linking libraries
@section Linking libraries
@pindex ar
Without libtool, the programmer would invoke the @file{ar} command to
@ -561,7 +563,7 @@ importance.
So, let's try again, this time with the library object
files:@footnote{Remember that we need to add @kbd{-lm} to the link
command line because @file{foo.c} uses the cos(3) math library
function. @xref{Using Libtool}.}
function. @xref{Using libtool}.}
@example
a23$ @kbd{libtool gcc -g -O -o libhello.la foo.lo hello.lo -lm}
@ -607,8 +609,8 @@ 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
@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
@ -719,8 +721,8 @@ 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 Installing Libraries
@section Installing Libraries
@node Installing libraries
@section Installing libraries
@pindex strip
Installing libraries on a non-libtool system is quite
@ -756,7 +758,7 @@ a23#
Note that the libtool library @file{libhello.la} is also installed, for
informational purposes, and to help libtool with uninstallation
(@pxref{Uninstall Mode}).
(@pxref{Uninstall mode}).
Here is the shared library example:
@ -800,13 +802,13 @@ 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
@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
libraries (@pxref{Linking executables}), you need to use libtool to
install the executables after the libraries have been installed
(@pxref{Installing Libraries}).
(@pxref{Installing libraries}).
So, for our Ultrix example, we would run:
@ -825,8 +827,8 @@ install -c .libs/hell /usr/local/bin/hell
burger#
@end example
@node Static Libraries
@section Linking Static Libraries
@node Static libraries
@section Linking static libraries
@cindex Static linking
@cindex Convenience libraries
@ -935,15 +937,16 @@ Print libtool version information and exit.
@end table
@menu
* Compile Mode:: Creating library object files.
* Link Mode:: Generating executables and libraries.
* Install Mode:: Making libraries and executables public.
* Finish Mode:: Completing a library installation.
* Uninstall Mode:: Removing executables and libraries.
* Compile mode:: Creating library object files.
* Link mode:: Generating executables and libraries.
* Dlname mode:: Obtaining a filename to @code{dlopen(3)}.
* Install mode:: Making libraries and executables public.
* Finish mode:: Completing a library installation.
* Uninstall mode:: Removing executables and libraries.
@end menu
@node Compile Mode
@section Compile Mode
@node Compile mode
@section Compile mode
For @samp{compile} mode, @var{mode-args} is a compiler command to be
used in creating a `standard' object file. These arguments should begin
@ -957,8 +960,8 @@ suffix `.c' with the library object suffix, `.lo'.
If shared libraries are being built, any necessary PIC generation flags
are substituted into the compilation command.
@node Link Mode
@section Link Mode
@node Link mode
@section Link mode
@samp{link} mode links together object files (including library
objects) to form another library or to create an executable program.
@ -969,6 +972,10 @@ output file (with the @samp{-o} flag) from several object files.
The following components of @var{mode-args} are treated specially:
@table @samp
@item -export-dynamic
Allow symbols from @var{output-file} to be resolved with @code{dlsym(3)}
(@pxref{Dynamic modules}).
@item -L@var{libdir}
Search @var{libdir} for required libraries that have already been
installed.
@ -1011,8 +1018,19 @@ This method is called @dfn{incremental linking}.
Otherwise, an executable program is created.
@node Install Mode
@section Install Mode
@node Dlname mode
@section Dlname mode
The @samp{dlname} mode simply prints the name of a libtool library that
can be passed to the @code{dlopen(3)} function call (@pxref{Dynamic
modules}).
Each of the @var{mode-args} specifies a libtool library that was linked
using the @samp{-export-dynamic} option (@pxref{Link mode}). The names
of the modules to load are printed to standard output, one per line.
@node Install mode
@section Install mode
In @samp{install} mode, libtool interprets @var{mode-args} as an
installation command beginning with @file{cp}, or a BSD-compatible
@ -1024,8 +1042,8 @@ command.
The command is run, and any necessary unprivileged post-installation
commands are also completed.
@node Finish Mode
@section Finish Mode
@node Finish mode
@section Finish mode
@samp{finish} mode helps system administrators install libtool
libraries so that they can be located and linked into user programs.
@ -1034,8 +1052,8 @@ 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
@node Uninstall mode
@section Uninstall mode
This mode deletes installed libraries (and other files).
@ -1045,25 +1063,21 @@ files (typically @file{/bin/rm}).
The remaning @var{mode-args} are either flags for the deletion program
(beginning with a `-'), or the names of files to delete.
@ignore
FIXME: add in documentation when we do reinstallation of old versions.
@end ignore
@node Integrating Libtool
@chapter Integrating Libtool with Your Own Packages
@node Integrating libtool
@chapter Integrating libtool with your own packages
This chapter describes how to integrate libtool with your packages so
that your users can install hassle-free shared libraries.
@menu
* Makefile Rules:: Writing Makefile rules for libtool.
* Makefile rules:: Writing Makefile rules for libtool.
* Using Automake:: Automatically supporting libtool.
* Configuring:: Configuring libtool for a host system.
* Distributing:: What files to distribute with your package.
@end menu
@node Makefile Rules
@section Writing Makefile Rules for Libtool
@node Makefile rules
@section Writing Makefile rules for libtool
Libtool is fully integrated with Automake (@pxref{Top, , The Automake
Manual, automake, The Automake Manual}), starting with Automake
@ -1089,7 +1103,7 @@ was generated automatically from the @file{Makefile.am} by Automake).
@end enumerate
@node Using Automake
@section Using Automake with Libtool
@section Using Automake with libtool
Libtool library support is implemented under the @samp{LTLIBRARIES}
primary.
@ -1135,7 +1149,7 @@ should not specify it.
automake, The Automake Manual}, for more information.
@node Configuring
@section Configuring Libtool
@section 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
@ -1158,7 +1172,7 @@ Libtool has its own equivalent to the @file{configure} script,
@menu
* Invoking ltconfig:: @file{ltconfig} command line options.
* ltconfig Example:: Manually configuring a @file{libtool}.
* ltconfig example:: Manually configuring a @file{libtool}.
* AM_PROG_LIBTOOL:: Configuring @file{libtool} in @file{configure.in}.
@end menu
@ -1180,6 +1194,11 @@ and accepts the following options:
@item --disable-shared
Create a @file{libtool} that only builds static libraries.
@item --disable-static
Create a @file{libtool} that builds only shared libraries if they are
available. If only static libraries can be built, then this flag has
no effect.
@item --help
Display a help message and exit.
@ -1230,7 +1249,7 @@ The system linker to use (if the generated @file{libtool} requires one).
Program to use rather than checking for @file{ranlib}.
@end defvar
@node ltconfig Example
@node ltconfig example
@subsection Using @file{ltconfig}
Here is a simple example of using @file{ltconfig} to configure libtool
@ -1301,7 +1320,7 @@ will automatically add @code{AM_PROG_LIBTOOL} support to your
@file{configure} script.
@node Distributing
@section Including Libtool with Your Package
@section Including libtool with your package
In order to use libtool, you need to include the following files with
your package:
@ -1328,7 +1347,7 @@ use the @file{libtoolize} program.
@menu
* Invoking libtoolize:: @file{libtoolize} command line options.
* Autoconf .o Macros:: Autoconf macros that set object file names.
* Autoconf .o macros:: Autoconf macros that set object file names.
@end menu
@node Invoking libtoolize
@ -1385,8 +1404,8 @@ will put the files in the specified directory.
@file{libtoolize} displays hints for adding libtool support to your
package, as well.
@node Autoconf .o Macros
@subsection Autoconf @samp{.o} Macros
@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
@ -1421,7 +1440,7 @@ AC_OUTPUT(@dots{})
@end example
@node Versioning
@chapter Library Interface Versions
@chapter Library interface versions
The most difficult issue introduced by shared libraries is that of
creating and resolving runtime dependencies. Dependencies on programs
@ -1445,12 +1464,12 @@ require.
@menu
* Interfaces:: What are library interfaces?
* Libtool Versioning:: Libtool's versioning system.
* Updating Version Info:: Changing version information before releases.
* Libtool versioning:: Libtool's versioning system.
* Updating version info:: Changing version information before releases.
@end menu
@node Interfaces
@section What Are Library Interfaces?
@section What are library interfaces?
Interfaces for libraries may be any of the following (and more):
@ -1471,8 +1490,8 @@ sockets, pipes, and other inter-process communication protocols
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
@node Libtool versioning
@section Libtool's versioning system
Libtool has its own formal versioning system. It is not as flexible as
some, but it is definitely the simplest of the more powerful versioning
@ -1527,12 +1546,12 @@ 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 the Library Version Information
@node Updating version info
@section Updating the 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}).
during link mode (@pxref{Link mode}).
This flag accepts an argument of the form
@samp{@var{current}[:@var{revision}[:@var{age}]]}. So, passing
@ -1577,8 +1596,8 @@ set @var{age} to 0.
to the release of the package that you are making. This is an abuse
that only fosters misunderstanding of the purpose of library versions.
@node Library Tips
@chapter Tips for Interface Design
@node Library tips
@chapter Tips for interface design
Writing a good library interface takes a lot of practice and thorough
understanding of the problem that the library is intended to solve.
@ -1617,7 +1636,7 @@ inheritance in an object-oriented system.
If you are careful to document each of your library's global functions
and variables in header files, and include them in your source files,
then the compiler will let you know if you make any interface changes by
accident (@pxref{C Header Files}).
accident (@pxref{C header files}).
@item Use the @code{static} keyword (or equivalent) whenever possible
The fewer global functions your library has, the more flexibility you'll
@ -1627,11 +1646,11 @@ aren't interface changes.
@end table
@menu
* C Header Files:: How to write portable include files.
* C header files:: How to write portable include files.
@end menu
@node C Header Files
@section Writing C Header Files
@node C header files
@section Writing C header files
Writing portable C header files can be difficult, since they may be read
by different types of compilers:
@ -1641,7 +1660,7 @@ by different types of 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
names aren't mangled. @xref{C++ libraries}, for other issues relevant
to using C++ with libtool.
@item ANSI C compilers
@ -1733,8 +1752,68 @@ compilers, especially pre-ANSI compilers.
The @code{long double} type is not supported by many compilers.
@end itemize
@node Other Languages
@chapter Using Libtool with Other Languages
@node Dlopened modules
@chapter Dlopened modules
It can sometimes be confusing to discuss @dfn{dynamic linking}, because
the term is used to refer to two completely 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 transparant to the application.
@item
The application calling functions such as
@code{dlopen(3)},@footnote{HP-UX, to be different, uses a function named
@code{shl_load(3)}.} 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.
On most operating systems, dlopened modules must be compiled as PIC.
This restriction simplifies the implementation of the @code{dlopen(3)}
family of functions by avoiding symbol relocation. ``True'' dlopen
implementations (such as the unportable GNU DLD 3 implementation,
@xref{Top, , The DLD Manual, dld, The DLD Manual}) don't have this
restriction, as they can perform relocation at runtime.
As of version @value{VERSION}, libtool provides only minimal support for
dlopened modules, and this support is guaranteed to change and be
redesigned in the near future. Because there is not a very high
proportion of applications that use dlopening, adding this support to
libtool was not deemed a priority for the 1.0 release.
This chapter discusses the preliminary support that libtool offers, and
how you as a dlopen application developer might use libtool to generate
dlopen-accessible modules. It is important to remember that these are
experimental features, and not to rely on them for easy answers to the
problems associated with dlopened modules.
FIXME:
@node Exporting dynamic symbols
@section Exporting dynamic symbols
In order for a symbol to be dynamically resolved (typically using the
@code{dlsym(3)} function), it must be declared in the object module
where it is defined.
Libtool provides the @samp{-export-dynamic} link flag (@pxref{Link
mode}), which does this declaration. You need to use this flag if you
are linking a shared library that will be dlopened.
@node Other languages
@chapter Using libtool with other languages
Libtool was first implemented in order to add support for writing shared
libraries in the C language. However, over time, libtool is being
@ -1745,11 +1824,11 @@ 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:: Using libtool with C++.
* C++ libraries::
@end menu
@node C++ Libraries
@section Writing Libraries for C++
@node C++ libraries
@section Writing libraries for C++
Creating libraries of C++ code is a fairly straightforward process, and
differs from C code in only two ways:
@ -1785,12 +1864,12 @@ 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.
* 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
@node Libtool test suite
@section The libtool 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
@ -1803,12 +1882,12 @@ to make sure that it has the functionality demanded by the test
programs.
@menu
* Test Descriptions:: The contents of the test suite.
* When Tests Fail:: What to do when a test fails.
* 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
@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:
@ -1829,7 +1908,7 @@ package that uses libtool.
@item 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
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.
@ -1843,7 +1922,7 @@ directly into a program file.
@item suffix.test
When other programming languages are used with libtool (@pxref{Other
Languages}), the source files may end in suffixes other than @samp{.c}.
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.
@ -1853,8 +1932,8 @@ used in the libtool scripts. Checking for the existence of a file can
only be done in a portable way by using @code{test -f}.
@end table
@node When Tests Fail
@subsection When Tests Fail
@node When tests fail
@subsection When tests fail
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
@ -1872,8 +1951,8 @@ Another way to have the test programs produce output is to set the
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
@node Reporting bugs
@section Reporting bugs
If you think you have discovered a bug in libtool, you should think
twice: the libtool maintainer is notorious for passing the buck (or
@ -1889,7 +1968,7 @@ 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}).
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.
@ -1900,28 +1979,28 @@ listed there are specific to Emacs, but the priciple 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
@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 Maintainance Notes for Libtool
@chapter Maintainance 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.
* 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.
@end menu
@node New Ports
@section Porting libtool to New Systems
@node New ports
@section Porting libtool to new systems
To port libtool to a new system, you'll generally need the following
information:
@ -1949,8 +2028,8 @@ Some systems have special documentation on how to build and install
shared libraries.
@end table
@node Tested Platforms
@section Tested Platforms
@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:
@ -1959,8 +2038,8 @@ platforms where it claims to support shared libraries:
@include platforms.texi
@end example
@node Platform Quirks
@section Platform Quirks
@node Platform quirks
@section Platform quirks
This section is dedicated to the sanity of the libtool maintainer. It
describes the programs that libtool uses, how they vary from system to
@ -1974,7 +2053,7 @@ improve libtool, or write your own.
@menu
* Compilers:: Creating object files from source files.
* Reloadable Objects:: Binding object files together.
* Reloadable objects:: Binding object files together.
* Archivers:: Programs that create static archives.
* Strip:: Removing unnecessary linkage information.
@end menu
@ -2037,8 +2116,8 @@ Use @samp{-KPIC} to generate PIC.
Use @samp{-PIC} to generate PIC.
@end table
@node Reloadable Objects
@subsection Reloadable Objects
@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
@ -2058,7 +2137,7 @@ must be used to ``bless'' the created library before linking against it,
with the @kbd{ranlib lib@var{name}.a} command.
@node Strip
@subsection The @file{strip} Program
@subsection The @file{strip} program
Stripping a library is essentially the same problem as stripping an
object file. Only local and debugging symbols must be removed, or else
@ -2083,8 +2162,8 @@ HP-UX @file{strip} requires the @samp{-r} and @samp{-x} flags in order
to strip libraries.
@end table
@node libtool Script Contents
@section @file{libtool} Script Contents
@node libtool script contents
@section @file{libtool} script contents
The @file{libtool} script is generated by @file{ltconfig}
(@pxref{Configuring}). Ever since libtool version 0.7, this script

12
libtool.m4 vendored
View File

@ -1,4 +1,4 @@
## libtool.m4 - Configure libtool for the target system.
## libtool.m4 - Configure libtool for the target system. -*-Shell-script-*-
## Copyright (C) 1996, 1997 Free Software Foundation, Inc.
## Gordon Matzigkeit <gord@gnu.ai.mit.edu>, 1996
##
@ -21,7 +21,7 @@
## configuration script generated by Autoconf, you may include it under
## the same distribution terms that you use for the rest of that program.
# serial 4 AM_PROG_LIBTOOL
# serial 5 AM_PROG_LIBTOOL
AC_DEFUN(AM_PROG_LIBTOOL,
[AC_REQUIRE([AC_CANONICAL_HOST])
AC_REQUIRE([AC_PROG_CC])
@ -37,7 +37,13 @@ AC_ARG_ENABLE(shared,
test "$enableval" = no && libtool_shared=" --disable-shared",
libtool_shared=)
libtool_flags="$libtool_shared"
dnl Allow the --disable-static flag to stop us from building static libs.
AC_ARG_ENABLE(static,
[ --enable-static build static libraries [default=yes]],
test "$enableval" = no && libtool_static=" --disable-static",
libtool_static=)
libtool_flags="$libtool_shared$libtool_static"
test "$silent" = yes && libtool_flags="$libtool_flags --silent"
test "$ac_cv_prog_gcc" = yes && libtool_flags="$libtool_flags --with-gcc"

18
ltconfig.in
View File

@ -87,6 +87,7 @@ Usage: $progname [OPTION]... LTMAIN [HOST]
Generate a system-specific libtool script.
--disable-shared do not build shared libraries
--disable-static do not build static libraries
--help display this help and exit
--no-verify do not verify that HOST is a valid host type
--quiet same as \`--silent'
@ -105,6 +106,8 @@ EOM
--disable-shared) enable_shared=no ;;
--disable-static) enable_static=no ;;
--quiet | --silent) silent=yes ;;
--srcdir) prev=srcdir ;;
@ -500,6 +503,8 @@ with_gnu_ld=no
set dummy $LD
linker="$2"
echo $ac_n "checking if $LD is GNU ld... $ac_c" 1>&6
# I'd rather use --version here, but apparently some GNU ld's don't accept
# it, but do accept -v.
if $LD -v 2>&1 | egrep '(GNU ld|with BFD)' > /dev/null; then
with_gnu_ld=yes
linker="GNU ld"
@ -562,13 +567,20 @@ else
hardcode_minus_L=yes
;;
freebsd*)
freebsd2*)
archive_cmds='$LD -Bshareable -o $lib$libobjs$deplibs'
hardcode_direct=yes
hardcode_minus_L=yes
hardcode_shlibpath_var=no
;;
freebsd3*)
archive_cmds='$CC -shared -o $lib$libobjs$deplibs'
hardcode_direct=yes
hardcode_minusL=yes
hardcode_shlibpath_var=no
;;
hpux9*)
archive_cmds='$rm $objdir/$soname;$LD -b +s +b $install_libdir -o $objdir/$soname$libobjs$deplibs;mv $objdir/$soname $lib'
hardcode_libdir_flag_spec='${wl}+b ${wl}$libdir'
@ -687,7 +699,7 @@ aix3* | aix4*)
soname_spec='$libname.so.$major'
;;
freebsd*)
freebsd2* | freebsd3*)
version_type=sunos
library_names_spec='$libname.so.$versuffix $libname.so'
finish_cmds='ldconfig -m $libdir'
@ -822,6 +834,8 @@ echo "$ac_t""$enable_shared" 1>&6
# Make sure either enable_shared or enable_static is yes.
test "$enable_shared" = yes || enable_static=yes
echo "checking whether to build static libraries... $enable_static" 1>&6
ofile=libtool
trap "$rm $ofile; exit 1" 1 2 15
echo creating $ofile

95
ltmain.sh.in
View File

@ -288,18 +288,15 @@ if test -z "$show_help"; then
hardcode_libdirs=
install_libdir=
libobjs=
libobjlibs=
link_against_libtool_libs=
link_static=
ltlibs=
objs=
output=
prev=
prevarg=
perm_rpath=
temp_rpath=
vinfo=
whole_archive=no
# We need to know -static, to get the right output filenames.
case " $@ " in
@ -350,8 +347,6 @@ if test -z "$show_help"; then
-l*) deplibs="$deplibs $arg" ;;
-no-whole-archive) whole_archive=no ;;
-o) prev=output ;;
-rpath)
@ -376,8 +371,6 @@ if test -z "$show_help"; then
continue
;;
-whole-archive) whole_archive=yes ;;
-*) cc="$cc $arg" ;; # Some other compiler flag.
*.o)
@ -391,37 +384,8 @@ if test -z "$show_help"; then
dir=`echo "$arg" | sed 's%/[^/]*$%/%'`
test "$dir" = "$arg" && dir=
# If -whole-archive was specified, we need to link all the members.
if test "$whole_archive" = yes; then
if test -f $arg; then :
else
echo "$progname: \`$arg' does not exist" 1>&2
echo "$help" 1>&2
exit 1
fi
# Get the names of the members of the archive.
members=`$AR t $arg 2>/dev/null`
for m in $members; do
case "$m" in
*.lo) libobjs="$libobjs $dir$m" ;;
*.o)
if test "$build_libtool_libs" = yes; then
objs="$objs $dir$m"
else
libobjs="$libobjs $dir$m"
fi
;;
esac
done
elif test -f "$dir$objdir/$file"; then
# .libs/libfoo.a exists, so this is an archive of libobjects.
libobjlibs="$libobjlibs $dir$objdir/$file"
arg="$dir$objdir/$file"
else
# Standard archive.
objs="$objs $arg"
fi
# Standard archive.
objs="$objs $arg"
;;
*.lo)
@ -641,9 +605,6 @@ if test -z "$show_help"; then
exit 1
fi
# Incorporate all of the convenience libraries.
libobjs="$libobjs"`echo "$libobjlibs" | sed "s%/$objdir/%/%g"`
# How the heck are we supposed to write a wrapper for a shared library?
if test -n "$link_against_libtool_libs"; then
echo "$progname: libtool library \`$output' may not depend on uninstalled libraries:$link_against_libtool_libs" 1>&2
@ -839,9 +800,7 @@ if test -z "$show_help"; then
$run $rm $obj $libobj
# Create the old-style object.
# FIXME: simplistically, we include all libobjlibs here.
# We really should determine which members are needed to resolve symbols.
reload_objs="$objs"`echo "$libobjs " | sed 's/[^ ]*\.a //g; s/\.lo /.o /g; s/ $//g'`"$libobjlibs"
reload_objs="$objs"`echo "$libobjs " | sed 's/[^ ]*\.a //g; s/\.lo /.o /g; s/ $//g'`
output="$obj"
cmds=`eval echo \"$reload_cmds\"`
@ -1059,12 +1018,13 @@ EOF
# See if we need to build an old-fashioned archive.
if test "$build_old_libs" = "yes"; then
# Now set the variables for building old libraries.
oldlib="$objdir/$libname.a"
case "$output" in
*.a) oldlib="$output" ;;
*) oldlib="$objdir/$libname.a" ;;
esac
# Transform .lo files to .o files.
# FIXME: simplistically, we include all libobjlibs here.
# We really should determine which members are needed to resolve symbols.
oldobjs="$objs"`echo "$libobjs " | sed 's/[^ ]*\.a //g; s/\.lo /.o /g; s/ $//g'`"$libobjlibs"
oldobjs="$objs"`echo "$libobjs " | sed 's/[^ ]*\.a //g; s/\.lo /.o /g; s/ $//g'`
if test -d "$objdir"; then
$show "$rm $oldlib"
@ -1083,38 +1043,6 @@ EOF
eval "$run $cmd" || exit $?
done
IFS="$save_ifs"
case "$output" in
*.a)
# Just move into place if there were any non-libtool objects.
if test -n "$objs"; then
$show "$mv $oldlib $output"
$run $mv $oldlib $output
elif test -z "$pic_flag" || test "$build_libtool_libs" != yes; then
# Just symlink if libtool objects are the same.
$show "$rm $output"
$run $rm $output
$show "$ln_s $oldlib $output"
$run $ln_s $oldlib $output
else
# Create an archive of libtool objects.
oldlib="$output"
oldobjs="$libobjs"
# Do each command in the archive commands.
cmds=`eval echo \"$old_archive_cmds\"`
IFS="${IFS= }"; save_ifs="$IFS"; IFS=';'
for cmd in $cmds; do
IFS="$save_ifs"
$show "$cmd"
eval "$run $cmd" || exit $?
done
IFS="$save_ifs"
fi
;;
esac
fi
# Now create the libtool archive.
@ -1716,16 +1644,14 @@ a program from several object files.
The following components of LINK-COMMAND are treated specially:
-export-dynamic allow the output file to be loaded with dlopen(3)
-export-dynamic allow symbols from OUTPUT-FILE to be resolved with dlsym(3)
-LLIBDIR search LIBDIR for required installed libraries
-lNAME OUTPUT-FILE requires the installed library libNAME
-no-whole-archive turn off \`-whole-archive'
-o OUTPUT-FILE create OUTPUT-FILE from the specified objects
-rpath LIBDIR the created library will eventually be installed in LIBDIR
-static do not do any dynamic linking or shared library creation
-version-info CURRENT[:REVISION[:AGE]]
specify library version info [each variable defaults to 0]
-whole-archive use all members from subsequent \`.a' files
All other options (arguments beginning with \`-') are ignored.
@ -1737,8 +1663,7 @@ If the OUTPUT-FILE ends in \`.la', then a libtool library is created, only
library objects (\`.lo' files) may be specified, and \`-rpath' is required.
If OUTPUT-FILE ends in \`.a', then a standard library is created using \`ar'
and \`ranlib'. If only libtool objects are specified, then the output file
may be used in the creation of other libtool archives.
and \`ranlib'.
If OUTPUT-FILE ends in \`.lo' or \`.o', then a reloadable object file is
created, otherwise an executable program is created.