4. Invoking libtool

The libtool program has the following synopsis:

libtool [option]… [mode-arg]…

and accepts the following options:

` --config'

Display libtool configuration variables and exit.

` --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 less (or more) or redirect to a file.

` -n'

` --dry-run'

Don't create, modify, or delete any files, just show what commands would be executed by libtool.

` --features'

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

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

` --finish'

Same as `--mode=finish'.

` --help'

Display a help message and exit. If `--mode=mode' is specified, then detailed help for mode is displayed.

` --mode=mode'

Use mode as the operation mode. If not specified, an attempt is made to infer the operation mode from the mode-args. Not specifying the mode is currently deprecated, as there are too many situations where it is not possible to guess. Future versions of Libtool will require that mode be explicitly set.

mode must be set to one of the following:

` compile'

Compile a source file into a libtool object.

` execute'

Automatically set the library path so that another program can use uninstalled libtool-generated programs or libraries.

` finish'

Complete the installation of libtool libraries on the system.

` install'

Install libraries or executables.

` link'

Create a library or an executable.

` uninstall'

Delete installed libraries or executables.

` clean'

Delete uninstalled libraries or executables.

` --version'

Print libtool version information and exit.

The mode-args are a variable number of arguments, depending on the selected operation mode. In general, each mode-arg is interpreted by programs libtool invokes, rather than libtool itself.

4.1 Compile mode

For compile mode, 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 `-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. `.c' for C source code) with the library object suffix, `.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 `-XCClinker flag' or pass linker flags with `-Wl,flag' and `-Xlinker flag'. You can also pass compile specific flags using `-Wc,flag' and `-Xcompiler 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 `-no-suppress' option is given in compile mode, libtool will show the compiler output for both objects.

If the `-static' option is given, then a `.o' file is built, even if libtool was configured with `--disable-static'.

Note that the `-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

libtool gcc -c foo/x.c -o foo/x.lo

will do what you expect.

Note, however, that, if the compiler does not support `-c' and `-o', it is impossible to compile `foo/x.c' without overwriting an existing `./x.o'. Therefore, if you do have a source file `./x.c', make sure you introduce dependencies in your `Makefile' to make sure `./x.o' (or `./x.lo') is re-created after any sub-directory's `x.lo':

x.o x.lo: foo/x.lo bar/x.lo

This will also ensure that make won't try to use a temporarily corrupted `x.o' to create a program or library. It may cause needless recompilation on platforms that support `-c' and `-o' together, but it's the only way to make it safe for those that don't.

4.2 Link mode

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

mode-args consist of a command using the C compiler to create an output file (with the `-o' flag) from several object files.

The following components of mode-args are treated specially:

` -all-static'

If output-file is a program, then do not link it against any shared libraries at all. If output-file is a library, then only create a static library.

` -avoid-version'

Tries to avoid versioning (see section Library interface versions) 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.

` -dlopen file'

Same as `-dlpreopen file', if native dlopening is not supported on the host platform (see section Dlopened modules) or if the program is linked with `-static' or `-all-static'. Otherwise, no effect. If file is self libtool will make sure that the program can dlopen itself, either by enabling -export-dynamic or by falling back to `-dlpreopen self'.

` -dlpreopen file'

Link file into the output program, and add its symbols to lt_preloaded_symbols (see section Dlpreopening). If file is self, the symbols of the program itself will be added to lt_preloaded_symbols. If file is force libtool will make sure that lt_preloaded_symbols is always defined, regardless of whether it's empty or not.

` -export-dynamic'

Allow symbols from output-file to be resolved with dlsym (see section Dlopened modules).

` -export-symbols symfile'

Tells the linker to export only the symbols listed in symfile. The symbol file should end in `.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.

` -export-symbols-regex regex'

Same as `-export-symbols', except that only symbols matching the regular expression regex are exported. By default all symbols are exported.

` -Llibdir'

Search libdir for required libraries that have already been installed.

` -lname'

output-file requires the installed library `libname'. This option is required even when output-file is not an executable.

` -module'

Creates a library that can be dlopened (see section 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.

` -no-fast-install'

Disable fast-install mode for the executable output-file. Useful if the program won't be necessarily installed.

` -no-install'

Link an executable 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.

` -no-undefined'

Declare that output-file does not depend on any other libraries. Some platforms cannot create shared libraries that depend on other libraries (see section Inter-library dependencies).

` -o output-file'

Create output-file from the specified objects and libraries.

` -objectlist file'

Use a list of object files found in file to specify objects.

` -precious-files-regex regex'

Prevents removal of files from the temporary output directory whose names match this regular expression. You might specify `\.bbg?$' to keep those files created with gcc -ftest-coverage for example.

` -release release'

Specify that the library was generated by release 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 `-version-info' flag instead (see section Library interface versions).

` -rpath libdir'

If output-file is a library, it will eventually be installed in libdir. If output-file is a program, add libdir to the run-time path of the program.

` -shrext suffix'

If output-file is a libtool library, replace the system's standard file name extension for shared libraries with suffix (most systems use `.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.

` -R libdir'

If output-file is a program, add libdir to its run-time path. If output-file is a library, add -Rlibdir to its dependency_libs, so that, whenever the library is linked into a program, libdir will be added to its run-time path.

` -static'

If output-file is a program, then do not link it against any uninstalled shared libtool libraries. If output-file is a library, then only create a static library.

` -version-info current[:revision[:age]]'

If output-file is a libtool library, use interface version information current, revision, and age to build it (see section Library interface versions). Do not use this flag to specify package release information, rather see the `-release' flag.

` -version-number major[:minor[:revision]]'

If 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 `-version-info' flag instead.

` -Wl,flag'

` -Xlinker flag'

Pass a linker specific flag directly to the linker.

` -XCClinker flag'

Pass a link specific flag to the compiler driver (CC) during linking.

If the output-file ends in `.la', then a libtool library is created, which must be built only from library objects (`.lo' files). The `-rpath' option is required. In the current implementation, libtool libraries may not depend on other uninstalled libtool libraries (see section Inter-library dependencies).

If the output-file ends in `.a', then a standard library is created using ar and possibly ranlib.

If output-file ends in `.o' or `.lo', then a reloadable object file is created from the input files (generally using `ld -r'). This method is often called partial linking.

Otherwise, an executable program is created.

4.3 Execute mode

For execute mode, the library path is automatically set, then a program is executed.

The first of the mode-args is treated as a program name, with the rest as arguments to that program.

The following components of mode-args are treated specially:

` -dlopen file'

Add the directory containing file to the library path.

This mode sets the library path environment variable according to any `-dlopen' flags.

If any of the 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.

4.4 Install mode

In install mode, libtool interprets most of the elements of mode-args as an installation command beginning with cp, or a BSD-compatible install program.

The following components of mode-args are treated specially:

` -inst-prefix inst-prefix-dir'

When installing into a temporary staging area, rather than the final prefix, this argument is used to reflect the temporary path, in much the same way automake uses DESTDIR. For instance, if prefix is /usr/local, but inst-prefix-dir is /tmp, then the object will be installed under /tmp/usr/local/. If the installed object is a libtool library, then the internal fields of that library will reflect only prefix, not inst-prefix-dir:

# Directory that this library needs to be installed in: libdir='/usr/local/lib'

not

# Directory that this library needs to be installed in: libdir='/tmp/usr/local/lib'

inst-prefix is also used to insure that if the installed object must be relinked upon installation, that it is relinked against the libraries in inst-prefix-dir/prefix, not prefix.

In truth, this option is not really intended for use when calling libtool directly; it is automatically used when libtool --mode=install calls libtool --mode=relink. Libtool does this by analyzing the destination path given in the original libtool --mode=install command and comparing it to the expected installation path established during libtool --mode=link.

Thus, end-users need change nothing, and automake-style make install DESTDIR=/tmp will Just Work(tm).

The rest of the mode-args are interpreted as arguments to the cp or install command.

The command is run, and any necessary unprivileged post-installation commands are also completed.

4.5 Finish mode

Finish mode helps system administrators install libtool libraries so that they can be located and linked into user programs.

Each mode-arg is interpreted as the name of a library directory. Running this command may require superuser privileges, so the `--dry-run' option may be useful.

4.6 Uninstall mode

Uninstall mode deletes installed libraries, executables and objects.

The first mode-arg is the name of the program to use to delete files (typically `/bin/rm').

The remaining mode-args are either flags for the deletion program (beginning with a `-'), or the names of files to delete.

4.7 Clean mode

Clean mode deletes uninstalled libraries, executables, objects and libtool's temporary files associated with them.

The first mode-arg is the name of the program to use to delete files (typically `/bin/rm').

The remaining mode-args are either flags for the deletion program (beginning with a `-'), or the names of files to delete.

This document was generated by System Administrator on February, 19 2008 using texi2html 1.70.