libtool.texi

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

@node Invoking libtool
@chapter Invoking @code{libtool}
@pindex libtool
@cindex libtool command options
@cindex options, libtool command
@cindex command options, libtool

The @code{libtool} program has the following synopsis:

@example
libtool [@var{option}]@dots{} [@var{mode-arg}]@dots{}
@end example

@noindent
and accepts the following options:

@table @samp
@item --config
Display libtool configuration variables and exit.

@item --debug
Dump a trace of shell script execution to standard output.  This
produces a lot of output, so you may wish to pipe it to @code{less} (or
@code{more}) or redirect to a file.

@item -n
@itemx --dry-run
Don't create, modify, or delete any files, just show what commands would
be executed by libtool.

@item --features
Display basic configuration options.  This provides a way for packages
to determine whether shared or static libraries will be built.

@item --tag=@var{tag}
Use configuration variables from tag @var{tag} (@pxref{Tags}).

@item --preserve-dup-deps
Do not remove duplicate dependencies in libraries.  When building packages
with static libraries, the libraries may depend circularly on each other
(shared libs can too, but for those it doesn't matter), so there are
situations, where -la -lb -la is required, and the second -la may not be
stripped or the link will fail.  In cases where these duplications are
required, this option will preserve them, only stripping the libraries
that libtool knows it can safely.

@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.  If not specified, an attempt is
made to infer the operation mode from the @var{mode-args}.  Not specifying
the @var{mode} is currently deprecated, as there are too many situations
where it is not possible to guess.  Future versions of Libtool will require
that @var{mode} be explicitly set.

@var{mode} must be set to 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 link specific
flags to the compiler driver using @samp{-XCClinker @var{flag}} or pass
linker flags with @samp{-Wl,@var{flag}} and @samp{-Xlinker @var{flag}}.
You can also pass compile specific flags using @samp{-Wc,@var{flag}}
and @samp{-Xcompiler @var{flag}}.

If both PIC and non-PIC objects are being built, libtool will normally
suppress the compiler output for the PIC object compilation to save
showing very similar, if not identical duplicate output for each
object.  If the @samp{-no-suppress} option is given in compile mode,
libtool will show the compiler output for both objects.

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}, @samp{-static-libtool-libs},
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 on systems that allow hardcoding
of library paths.  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 -objectlist @var{file}
Use a list of object files found in @var{file} to specify objects.

@item -precious-files-regex @var{regex}
Prevents removal of files from the temporary output directory whose
names match this regular expression.  You might specify @samp{\.bbg?$}
to keep those files created with @code{gcc -ftest-coverage} for example.

@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 -shrext @var{suffix}
If @var{output-file} is a libtool library, replace the system's standard
file name extension for shared libraries with @var{suffix} (most systems
use @file{.so} here).  This option is helpful in certain cases where an
application requires that shared libraries (typically modules) have an
extension other than the default one.  Please note you must supply the
full file name extension including any leading dot.

@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 -static-libtool-libs
If @var{output-file} is a program, then do not link it against any
shared libtool libraries (@samp{.la} files).  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 -version-number @var{major}[:@var{minor}[:@var{revision}]]
If @var{output-file} is a libtool library, compute interface version
information so that the resulting library uses the specified major, minor and
revision numbers.  This is designed to permit libtool to be used with
existing projects where identical version numbers are already used across
operating systems.  New projects should use the @samp{-version-info} flag
instead.

@item -Wl,@var{flag}
@itemx -Xlinker @var{flag}
Pass a linker specific flag directly to the linker.

@item -XCClinker @var{flag}
Pass a link specific flag to the compiler driver (@var{CC}) during linking.
@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.