libtool.texi

GNU libtool 是一个通用库支持脚本

\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

@ifnottex
This file documents GNU Libtool @value{VERSION}

Copyright (C) 1996-2003, 2005-2007 Free Software Foundation, Inc.

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1
or any later version published by the Free Software Foundation;
with no Invariant Sections, with no Front-Cover Texts,
and with no Back-Cover Texts.  A copy of the license is included in
the section entitled "GNU Free Documentation License".

@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
@end ifnottex

@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-2003, 2005-2007 Free Software Foundation, Inc.

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1
or any later version published by the Free Software Foundation;
with no Invariant Sections, with no Front-Cover Texts,
and with no Back-Cover Texts.  A copy of the license is included in
the section entitled "GNU Free Documentation License".

@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

@ifnottex
@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.
* GNU Free Documentation License:: License for this manual.
* 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.
* Thread Safety in libltdl::	Registering callbacks for multi-thread safety.
* User defined module data::    Associating data with loaded modules.
* Module loaders for libltdl::  Creating user defined module loaders.
* Distributing libltdl::        How to distribute libltdl with your package.

Using libtool with other languages

* C++ libraries::               Writing libraries for C++
* Tags::                        Tags

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.
* Multiple dependencies::	Removing duplicate dependent libraries.
* Archivers::                   Programs that create static archives.

@end detailmenu
@end menu

@end ifnottex

@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.