Главная   Изменения   Спек   Патчи   Исходники   Загрузить   Gear   Bugs and FR  Repocop 

.\" You may copy, distribute and modify under the terms of the LDP General
.\" Public License as specified in the LICENSE file that comes with the
.\" gnumaniak distribution
.\"
.\" The author kindly requests that no comments regarding the "better"
.\" suitability or up-to-date notices of any info documentation alternative
.\" is added without contacting him first.
.\"
.\" (C) 1999 Ragnar Hojland Espinosa <ragnar@macula.net>
.\"
.\"	libtool man page
.\"	man pages are NOT obsolete!
.\"	<ragnar@macula.net>
.TH LIBTOOL 301 "December 1999" "libtool 1.3.4"
.SH NAME
\fBlibtool\fR \- compile, build, install and uninstall libraries
.SH SYNOPSIS
.B libtool
.RB [ \-n ]
.RB [ \-\-config ]
.RB [ \-\-debug ]
.RB [ \-\-dry\-run ]
.RB [ \-\-finish ]
.RB [ \-\-mode=\fIMODE ]
.RB [ \-\-quiet ] 
.RB [ \-\-silent ]
.RI [ MODE\-ARGS... ]

Link Mode: [\fB\-l\fINAME\fR] [\fB\-o \fI OUTPUT\-FILE\fR] [\fB\-L\fILIBDIR\fR]
[\fB\-R \fILIBDIR\fR]
.RB [ \-all\-static ]
.RB [ \-avoid\-version ]
.RB [ "\-dlopen \fIFILE" ]
.RB [ "\-dlpreopen \fIFILE" ]
.RB [ \-export\-dynamic ]
.RB [ "\-\-export\-symbols \fIFILE" ]
.RB [ "\-\-export\-symbols \fIREGEX" ]
.RB [ \-\-module ]
.RB [ \-no\-undefined ]
.RB [ "\-release \fIRELEASE" ]
.RB [ "\-rpath \fILIBDIR" ]
.RB [ \-static ]
.RB [ "\-version\-info \fICURRENT\fR[\fB:\fIREVISION\fR[\fB:\fIAGE" ]]

Execute Mode: [\fB\-dlopen \fIFILE\fR]

.BR libtool " [" \-\-features "] [" \-\-help "] [" \-\-version ]
.SH DESCRIPTION
.B libtool
simplifies the complexity of compiling, linking, installing and unistalling
both static and shared libraries so that the complete functionality of
different platforms is available via a generic interface but nasty quirks
are hidden from the programmer.

.B libtool
can operate in six modes: compile, execute, link, finish, install, uninstall.
.SS Compile Mode
For \fBcompile\fR mode, \fIMODE\-ARGS\fR 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 \fB\-c\fR compiler flag so that
only an object file is created.

\fBlibtool\fR determines the name of the output file by removing the
directory component from the source file name, then substituting the C
source code 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.  The \fB\-static\fR
option will cause \fBlibtool\fR to generate `.o' files even if it was
configured with \fB\-\-disable\-static\fR

The \fB\-o\fR option is emulated on platforms that don't support it directly
(by locking and moving the object files generated by the compiler) so you
can use the usual syntax:
.sp
.RS
.nf
lightside:% libtool cc -c foo/x.c -o foo/x.lo
.fi
.RE
.sp
If the platform doesn't support \fB\-c\fR and \fB\-o\fR then it is
impossible to build `foo/x.lo' without overwriting an old `foo/x.o', and
that in this case you must make sure `foo/x.o' is (re)built after `foo/x.lo'

.SS Link Mode
\fBlink\fR mode links together object files (including library objects)
to form another library or to create an executable program.

\fIMODE\-ARGS\fR consist of a command using the C compiler to create an
output file \fIOUTPUT\-FILE\fR (with the \fB\-o\fR flag) from several object
files.  The type of file depends on the extension of \fIOUTPUT\-FILE\fR:
.TP
.B .la
A libtool library is created, which must be built only from library objects
(`.lo' files).  The \fB\-rpath\fR option is required.  In the current
implementation, libtool libraries may not depend on other uninstalled
libtool libraries.
.TP
.B .a
A standard library is created using \fBar\fR(1) and possibly \fBranlib\fR(1).
.TP
.B .o .lo
A reloadable object file is created from the input files (generally using
`ld \-r').  This method is often called ``partial linking''.
.TP
.B other
An executable program is created.
.SS Execute Mode
For \fBexecute\fR mode, the library path environment variable is
automatically set (and modified according \fB\-dlopen\fR), then a program
is executed.

The first of the \fIMODE-ARGS\fR is treated as a program name, with the
rest as arguments to that program.

If any of the arguments 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.
.SS Install Mode
In \fBinstall\fR mode, libtool interprets \fIMODE\-ARGS\fR as an installation
command beginning with \fBcp\fR(1), or a BSD-compatible \fBinstall\fR(1)
program.

The rest of the \fBMODE\-ARGS\fR are interpreted as arguments to that
command.

The command is run, and any necessary unprivileged post-installation
commands are also completed.
.SS Finish Mode
\fBfinish\fR mode helps system administrators install libtool libraries
so that they can be located and linked into user programs.

Each \fIMODE\-ARG\fR is interpreted as the name of a library directory.
Running this command may require superuser privileges, so the
\fB\-\-dry\-run\fR option may be useful.
.SS Uninstall Mode
This mode deletes installed libraries (and other files).

The first \fIMODE\-ARG\fR is the name of the program to use to delete files
(typically `/bin/rm').

The remaining \fIMODE\-ARGS\fR are either flags for the deletion program
(beginning with a `\-'), or the names of files to delete.
.SH OPTIONS
.SS Global Options
.TP
.B \-\-config
Display libtool's configuration variables and exit.
.TP
.B \-\-debug
Enables shell script trace mode, writing to standard output.
.TP
.B \-n, \-\-dry\-run
Don't create, modify, or delete any files, just show what commands
would be executed by \fBlibtool\fR.
.TP
.B \-\-finish
Same as \fB\-\-mode=finish\fR.
.TP
.B \-\-mode=\fIMODE
Use \fIMODE\fR as the operation mode.  By default, the
operation mode is inferred from the contents of \fIMODE\-ARGS\fR.
If \fIMODE\fR is specified, it must be one of the following:
.RS
.TP
.B compile
Compile a source file into a libtool object.
.TP
.B execute
Automatically set the library path so that another program
can use uninstalled libtool-generated programs or libraries.
.TP
.B finish
Complete the installation of libtool libraries on the system.
.TP
.B install
Install libraries or executables.
.TP
.B link
Create a library or an executable.
.TP
.B uninstall
Delete installed libraries or executables.
.RE
.TP
.B \-\-features
Display libtool configuration information and exit.  This provides
a way for packages to determine whether shared or static libraries will be
built.
.TP
.B "\-\-help"
Print a usage message on standard output and exit successfully.  If
\fB\-\-mode=\fIMODE\fR is specified, help on selected mode is printed.
.TP
.B "\-\-version"
Print version information on standard output then exit successfully.
.SS Link Mode Options
.TP
.B -l\fINAME
\fIOUTPUT\-FILE\fR requires the installed library \fBlib\fINAME\fR.  This
option is required even when \fIOUTPUT\-FILE\fR is not an executable.
.TP
.B \-o \fIOUTPUT\-FILE
Create \fIOUTPUT\-FILE\fR from the specified objects and libraries.
.TP
.B \-L\fILIBDIR
Search \fILIBDIR\fR for required libraries that have already been installed.
.TP
.B \-R \fILIBDIR
If \fIOUTPUT\-FILE\fR is an executable, add \fILIBDIR\fR to its run-time
path.  If \fIOUTPUT-FILE\fR is a library, add `-RLIBDIR' to its
\fBDEPENDENCY_LIBS\fR so that, whenever the library is linked into an
executable, \fILIBDIR\fR will be added to its run-time path.
.TP
.B \-all\-static
If \fIOUTPUT\-FILE\fR is a program, then do not link it against any
shared libraries at all.  If \fIOUTPUT-FILE\fR is a library, then only
create a static library.
.TP
.B \-avoid\-version
Tries to avoid using any kind of versioning (no version info is stored and
no symbolic links are created).  This option has no effect on platforms which
require versioning.
.TP
.B \-dlopen \fIFILE
Same as \fB\-dlpreopen \fIFILE\fR, if native dlopening is not
supported on the host platform or if the executable is linked using
\fB\-static\fR or \fB\-all\-static\fR.  Otherwise, no effect.

If \fIFILE\fR is `self', then libtool will make sure that the executable can
\fBdlopen\fR(3) itself by using \fB\-export\-dynamic\fR or \fB\-dlpreopen\fR.
.TP
.B \-dlpreopen \fIFILE
Link \fIFILE\fR into the output program, and add its symbols to
\fBLT_PRELOADED_SYMBOLS\fR.

If \fIFILE\fR is `self', then the symbols of the output program itself will
be added to \fBLT_PRELOADED_SYMBOLS\fR.
.TP
.B \-export\-dynamic
Allow symbols from \fIOUTPUT\-FILE\fR to be resolved with \fBdlsym\fR(3).
.TP
.B \-export\-symbols \fIFILE
On platforms which support it, the linker will only export symbols listed in
\fIFILE\fR.  The name of \fIFILE\fR must end in `.sym' and contain on symbol
per line.  By default all symbols are exported.
.TP
.B \-export\-symbols\-regex \fIREGEX
As \fB\-export\-symbols\fR, except that only symbols that match the
\fIREGEX\fR \fBregex\fR(7) are exported.
.TP
.B \-module
Creates a library that can be dlopened.  Module names don't need to be
prefixed with `lib', however in order to prevent name clashes `libname' and
`name' must not be used at the same time in your package.
.TP
.B \-no\-undefined
Declare that \fIOUTPUT\-FILE\fR does not depend on any other libraries.
Some platforms cannot create shared libraries that depend on other
libraries.
.TP
.B \-release \fIRELEASE
Specify that the library was generated by release \fIRELEASE\fR 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 \fB\-version\-info\fR flag.
.TP
.B \-rpath \fILIBDIR
If \fIOUTPUT\-FILE\fR is a library, it will eventually be installed in
\fILIBDIR\fR.
.TP
.B \-static
If \fIOUTPUT\-FILE\fR is a program, then do not link it against any
uninstalled shared libtool libraries.  If \fIOUTPUT\-FILE\fR is a
library, then only create a static library.
.TP
.B \-version\-info \fICURRENT\fR[\fB:\fIREVISION\fR[\fB:\fIAGE\fR]]
If \fIOUTPUT\-FILE\fR is a libtool library, use interface version
information \fICURRENT\fR, \fIREVISION\fR, and \fIAGE\fR to build it
Do \fBnot\fR use this flag to specify package release information, rather
see the \fR\-release\fB flag.
.SS Execute Mode Options
.TP
.B \-dlopen \fIFILE
Add the directory containing \fIFILE\fR to the library path.
.SH VERSIONING
.B libtool
has it's own versioning system for shared libraries. If you want to use this
system, you must use the \fB\-version\-info\fR option.  This option accepts
an argument of the form \fICURRENT\fR[\fB:\fIREVISION\fR[\fB:\fIAGE\fR]]
.TP
.I CURRENT
Interface version, understanding interface as anything visible to the
"outside" world: variables, function prototypes, output format, etc.
.TP
.I REVISION
Implementation version, relative to \fICURRENT\fR version.
.TP
.I 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 `\fICURRENT \- \fIAGE\fR' to
\fICURRENT\fR, and any executable can use the library if it has been linked
against a library in this range.
.PP
If either \fIREVISION\fR or \fIAGE\fR are omitted, they default to 0.  Also
note that \fIAGE\fR must be less than or equal to the \fICURRENT\fR
interface number.  If two libraries have identical \fICURRENT\fR and \fIAGE\fR
numbers, then the dynamic linker chooses the library with the greater
\fIREVISION\fR.

Some versioning guidelines:

\fB\(bu\ 1.\fR Start with version information of `0:0:0' for each libtool
library.

\fB\(bu\ 2.\fR 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.

\fB\(bu\ 3.\fR If the library source code has changed at all since
the last update, then increment \fIREVISION\fR (\fIC\fB:\fIR\fB:\fIA\fR
becomes \fIC\fB:\fIR+1\fB:A\fR). 

\fB\(bu\ 4.\fR If any interfaces have been added, removed, or changed since the
last update, increment \fICURRENT\fR, and set \fIREVISION\fR to 0.

\fB\(bu\ 5.\fR If any interfaces have been added since the last public release,
then increment \fIAGE\fR.

\fB\(bu\ 6.\fR If any interfaces have been removed since the last
public release, then set \fIAGE\fR to 0.

If you want to encode the package version in the library name, or use
another versioning system without conflicting with \fBlibtool\fR's
versioning, use \fB\-release\fR.  `libbfd.so.2.7.0.2' for example, comes with
binutils\-2.7.0.2 and clearly conflicts with \fBlibtool\fR's versioning.  We
can use `\-release 2.7.0' and end up with `libbfd\-2.7.0.so.0.0.0' which is ok.

Note that libraries with different \fICURRENT\fR version, and libraries with
different \fB\-release\fR, will be binary incompatible.
.SH INTERFACE DESIGN
Writing a good library interface takes 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 clients won't have to keep relearning how to use the
library. 

Some design guidelines:

\fB\(bu\fR Plan ahead
.br
Try to make every interface minimal, so that you won't need to delete entry
points very often.

\fB\(bu\fR Avoid interface changes
.br
If you must redesign an interface, try to leave compatibility functions
behind so that clients don't need to rewrite their existing code.

\fB\(bu\fR Use opaque data types
.br
The fewer data type definitions a client 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 client to directly
manipulate the data.  That way, you have the freedom to change the
data structures without changing the interface. 

\fB\(bu\fR Use header files
.br
If you write 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.

\fB\(bu\fR Use \fBstatic\fRs (or equivalent) whenever possible
.br
The fewer global functions your library has, the more flexibility
you will have in changing them.  \fBstatic\fR functions and variables may
change as often as you like, since clients cannot access them and therefore
they aren't considered interface changes.
.SH WRITING AUTOMAKE RULES
\fBlibtool\fR library support is implemented under the \fBLTLIBRARIES\fR
primary.

To link a program against a \fBlibtool\fR library, just use the
\fIprogram\fB_LDADD\fR variable to specify the library name.  You may use
\fIprogram\fB_LDFLAGS\fR to pass any options to libtool, such as
\fB\-static\fR. 

To build a \fBlibtool\fR library, use \fIlib\fB_LTLIBRARIES\fR to specify the
library name and \fB, and, for example, \fIlib\fB_LDFLAGS\fR to pass the
\fB\-version\-info\fR option to \fBlibtool\fR.  You will find an example in
the next section.

You will also have to include some basic files in your package, or use 
\fBlibtoolize\fR to do the work for you.  Do not include the \fBlibtool\fR
script directly.
.TP
.B config.guess
Attempt to guess a canonical system name.
.TP
.B config.sub
Canonical system name validation subroutine script.
.TP
.B ltconfig
Generate a libtool script for a given system.
.TP
.B ltmain.sh
A generic script implementing basic libtool functionality.
.SH DLOPENING MODULES
To use \fBlibtool\fR's dlopening support, you must use the macro
\fBAC_LIBTOOL_DLOPEN\fR in your \fBconfigure.in\fR, before
\fBAM_PROG_LIBTOOL\fR. Otherwise \fBlibtool\fR will assume there's no
dlopening mechanism available on the platform and will simulate it.
In order to use this simulation feature you must declare the objects you
want to dlopen by using the \fB\-dlopen\fR and \fB\-dlreopen\fR flags when
linking your executable. \fBlibtool\fR will link the object files and create
data structures holding the executable's symbol table:
.sp
.RS
.nf
struct lt_dlsymlist { const char *NAME; lt_ptr_t ADDRESS; }
.fi
.RE
.sp
\fINAME\fR holds an asciiz string with the symbol name, such as "fprintf".
\fIADDRESS\fR is a generic pointer to the appropriate object, such as
&fprintf.
.sp
.RS
.nf
const lt_dlsymlist * lt_preloaded_symbols;
.fi
.RE
.sp
This array represents all the preloaded symbols linked into the executable.
For each \fB\-dlpreloaded\fR file there is an element with the \fINAME\fR of
the file and a \fIADDRESS\fR of `\fB0\fR', followed by all symbols exported from
this file.  For the executable itself the special name \fB@PROGRAM@\fR is used.
The last element has a \fINAME\fR and \fIADDRESS\fR of `\fB0\fR'.


When linking either a library that is going to be dlopened or an executable
that is going to dlopen a module, remember to specify the \fB\-module\fR
flag.

If an executable needs to reference an external symbol of a library that you
are going to dlopen, use \fB\-export\-dynamic\fR when linking the executable.

Due variations in library names, your program needs to determine which is
the correct file to dlopen.  A straightforward approach is to examine the
`\fB.la\fR' files, looking for the \fBdlname='\fIDLNAME\fB'\fR line, where
\fBDLNAME\fR is either empty if the library can't be dlopened, or holds the
dlname of the library.

.SH EXAMPLES
We are about to create a library called `libbaz' from the source files
`foo.c', `bar.c', and then link `a.c' with `libbaz' to create an executable
named `a'
.SS Creating The Library
\fB\(bu\fR Compile mode: since Linux supports shared libraries, \fBlibtool\fR
will generate two object files: one for the static library (`foo.lo') and
one for the shared library (`foo.o').  The \fB\-c\fR option is mandatory,
since we don't want the compiler to do the linking on its own.
.sp
.RS
.nf
lightside:~% libtool cc \-c foo.c
cc \-c \-fPIC \-DPIC foo.c -o .libs/foo.lo
cc \-c foo.c >/dev/null 2>&1
lightside:~% libtool cc -c bar.c
cc \-c \-fPIC \-DPIC bar.c -o .libs/bar.lo
cc \-c bar.c >/dev/null 2>&1
.fi
.RE	     
.sp
\fB\(bu\fR Link mode, build only a static library: We specify the `.o'
object files generated previously.  The \fB\-o\fR option is mandatory.
.sp
.RS
.nf
lightside:~% libtool cc -o libbaz.a foo.o bar.o
ar cru libbaz.a foo.o bar.o
ranlib libbaz.a
.fi
.RE	     
.sp
\fB\(bu\fR Link mode, build static and shared libraries: We specify the
`.lo' object files.  Mandatory options are \fB\-o\fR like before, and
\fB\-rpath\fR to indicate which will be the installation directory for our
library.  The library will be created in the `.libs' directory.
.sp
.RS
.nf
lightside:~% libtool cc \-o libbaz.la foo.lo bar.lo \e
    \-rpath /usr/local/lib
cc \-shared \-Wl,\-soname \-Wl,libbaz.so.0 \e
    \-o .libs/libbaz.so.0.0.0 foo.lo bar.lo
(cd .libs && ln \-s libbaz.so.0.0.0 libbaz.so.0)
(cd .libs && ln \-s libbaz.so.0.0.0 libbaz.so)
ar cru .libs/libbaz.a foo.o bar.o
ranlib .libs/libbaz.a
creating libbaz.la
(cd .libs && ln \-s ../libbaz.la libbaz.la)
.fi
.RE	     
.sp
\fB\(bu\fR Install mode: This will run the necessary commands to install the
library in the specified path (in our case, `/usr/local/lib').  It will
install the shared (`.so') and static (`.a') libraries, as well as the
libtool file (`.la'), for unistallation and informational purposes.

Since this is often done as a privileged user, it's useful to specify the
\fB\-n\fR or \fB\-\-dry\-run\fR option to check the results.
.sp
.RS
.nf
lightside:/tmp% libtool \-n install libbaz.la /usr/local/lib
install .libs/libbaz.so.0.0.0 /usr/local/lib/libbaz.so.0.0.0
(cd /usr/local/lib && ln \-s libbaz.so.0.0.0 libbaz.so.0)
(cd /usr/local/lib && ln \-s libbaz.so.0.0.0 libbaz.so)
install libbaz.la /usr/local/lib/libbaz.la
install .libs/libbaz.a /usr/local/lib/libbaz.a
ranlib /usr/local/lib/libbaz.a
chmod 644 /usr/local/lib/libbaz.a
.fi
.RE	     
.sp
.SS Creating the Executable
First we compile `a.c'
.sp
.RS
.nf
cc \-c a.c
.fi
.RE	     
.sp
If the library has already been installed you can proceed as usual
.sp
.RS
.nf
cc a.c \-lbaz \-L/usr/local/lib
.fi
.RE	     
.sp
If the library hasn't been installed yet, \fBlibtool\fR must be used to 
do the linking, debugging and installation of the executable (this last thing,
once the library has been installed).  Note that the real executable will be
in `.libs' until it is installed, and the the executable on the work
directory is merely a wrapper.

In order to avoid ambiguities, never use \fB\-l\fR or \fB\-L\fR to link
against an uninstalled shared library.  Just specify the path to the `.la'
file.  Installed libraries aren't a problem, as we see below (`\-lm').
.sp
.RS
.nf
lightside:~% libtool cc a.o libbaz.la \-o a -lm
cc a.o \-Wl,\-\-rpath \-Wl,/usr/local/lib \e
    .libs/libbaz.so \-o .libs/a -lm
lightside:~% libtool gdb a
[snipped hairy debugging session]
lightside:~% libtool install \-c a /usr/local/bin/a
install \-c .libs/a /usr/local/bin/a
.fi
.RE	     
.sp
.SS Creating Makefile.am
\fB\(bu\fR\ First create a brief \fBconfigure.in\fR, remembering to add the
macros for \fBautomake\fR and \fBlibtool\fR.
.sp
.RS
.nf
AC_DEFUN(AM_INIT_AUTOMAKE)
AC_INIT(a.c)
AM_INIT_AUTOMAKE(a, 1.0)
AC_PROG_CC
AM_PROG_LIBTOOL
AC_OUTPUT(Makefile)
.fi
.RE
.sp
\fB\(bu\fR\ Then the corresponding \fBMakefile.am\fR
.sp
.RS
.nf
# Build the library
lib_LTLIBRARIES=libbaz.la
libbaz_la_SOURCES = foo.c bar.c
libbaz_la_LDFLAGS = -version-info 0:0:0

bin_PROGRAMS = a a.debug

# Build a from a.c and libbaz.la
a_SOURCES = a.c
a_LDADD = libbaz.la

# Create a static debugging version
a_debug_SOURCES = a.c
a_debug_LDADD = libbaz.la
a_debug_LDFLAGS = \-static
.fi
.RE
.sp
\fB\(bu\fR\ And finally give it a try
.sp
.RS
.nf
lightside:~% aclocal; libtoolize; automake \-\-add\-missing; autoconf
lightside:~% ./configure; make
.fi
.RE
.sp
.SH SEE ALSO
 \fBlibtoolize\fR(1), \fBlibltdl\fR(3)
.SH NOTES
Report bugs to <bug-libtool@gnu.org>.
.br
Man page by Ragnar Hojland Espinosa <ragnar@macula.net>