libtool.texi

这是一个自动生成MAKEFILE的工具。一个很有用的库。在LINUX工程项目里是很好的帮手。希望对大家有点帮助。

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: