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 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 -static option will cause libtool to generate `.o' files even if it was configured with --disable-static

The -o 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:

lightside:% libtool cc -c foo/x.c -o foo/x.lo

If the platform doesn't support -c and -o 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'

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 OUTPUT-FILE (with the -o flag) from several object files. The type of file depends on the extension of OUTPUT-FILE:

.la

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.

.a

A standard library is created using ar(1) and possibly ranlib(1).

.o .lo

A reloadable object file is created from the input files (generally using `ld -r'). This method is often called ``partial linking''.

other

An executable program is created.

Execute Mode

For execute mode, the library path environment variable is automatically set (and modified according -dlopen), 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.

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.

Install Mode

In install mode, libtool interprets MODE-ARGS as an installation command beginning with cp(1), or a BSD-compatible install(1) program.

The rest of the MODE-ARGS are interpreted as arguments to that command.

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

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.

Uninstall Mode

This mode deletes installed libraries (and other files).

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.

Global Options

--config

Display libtool's configuration variables and exit.

--debug

Enables shell script trace mode, writing to standard output.

-n, --dry-run

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

--finish

Same as --mode=finish.

--mode=MODE

Use MODE as the operation mode. By default, the operation mode is inferred from the contents of MODE-ARGS. If MODE is specified, it must be one of the following:

--features

Display libtool configuration information and exit. This provides a way for packages to determine whether shared or static libraries will be built.

--help

Print a usage message on standard output and exit successfully. If --mode=MODE is specified, help on selected mode is printed.

--version

Print version information on standard output then exit successfully.

Link Mode Options

-lNAME

OUTPUT-FILE requires the installed library libNAME. This option is required even when OUTPUT-FILE is not an executable.

-o OUTPUT-FILE

Create OUTPUT-FILE from the specified objects and libraries.

-LLIBDIR

Search LIBDIR for required libraries that have already been installed.

-R LIBDIR

If OUTPUT-FILE is an executable, 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 an executable, LIBDIR will be added to its run-time path.

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

-dlopen FILE

Same as -dlpreopen FILE, if native dlopening is not supported on the host platform or if the executable is linked using -static or -all-static. Otherwise, no effect.

If FILE is `self', then libtool will make sure that the executable can dlopen(3) itself by using -export-dynamic or -dlpreopen.

-dlpreopen FILE

Link FILE into the output program, and add its symbols to LT_PRELOADED_SYMBOLS.

If FILE is `self', then the symbols of the output program itself will be added to LT_PRELOADED_SYMBOLS.

-export-dynamic

Allow symbols from OUTPUT-FILE to be resolved with dlsym(3).

-export-symbols FILE

On platforms which support it, the linker will only export symbols listed in FILE. The name of FILE must end in `.sym' and contain on symbol per line. By default all symbols are exported.

-export-symbols-regex REGEX

As -export-symbols, except that only symbols that match the REGEX regex(7) are exported.

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

-no-undefined

Declare that OUTPUT-FILE does not depend on any other libraries. Some platforms cannot create shared libraries that depend on other libraries.

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

-rpath LIBDIR

If OUTPUT-FILE is a library, it will eventually be installed in LIBDIR.

-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 Do not use this flag to specify package release information, rather see the -release flag.

Execute Mode Options

-dlopen FILE

Add the directory containing FILE to the library path.

Creating The Library

• Compile mode: since Linux supports shared libraries, libtool will generate two object files: one for the static library (`foo.lo') and one for the shared library (`foo.o'). The -c option is mandatory, since we don't want the compiler to do the linking on its own.

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

• Link mode, build only a static library: We specify the `.o' object files generated previously. The -o option is mandatory.

lightside:~% libtool cc -o libbaz.a foo.o bar.o
ar cru libbaz.a foo.o bar.o
ranlib libbaz.a

• Link mode, build static and shared libraries: We specify the `.lo' object files. Mandatory options are -o like before, and -rpath to indicate which will be the installation directory for our library. The library will be created in the `.libs' directory.

lightside:~% libtool cc -o libbaz.la foo.lo bar.lo \


    -rpath /usr/local/lib
cc -shared -Wl,-soname -Wl,libbaz.so.0 \


    -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)

• 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 -n or --dry-run option to check the results.

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

Creating the Executable

First we compile `a.c'

cc -c a.c

If the library has already been installed you can proceed as usual

cc a.c -lbaz -L/usr/local/lib

If the library hasn't been installed yet, libtool 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 -l or -L 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').

lightside:~% libtool cc a.o libbaz.la -o a -lm
cc a.o -Wl,--rpath -Wl,/usr/local/lib \


    .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

Creating Makefile.am

• First create a brief configure.in, remembering to add the macros for automake and libtool.

AC_DEFUN(AM_INIT_AUTOMAKE)
AC_INIT(a.c)
AM_INIT_AUTOMAKE(a, 1.0)
AC_PROG_CC
AM_PROG_LIBTOOL
AC_OUTPUT(Makefile)

• Then the corresponding Makefile.am

# 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

• And finally give it a try

lightside:~% aclocal; libtoolize; automake --add-missing; autoconf
lightside:~% ./configure; make