Next: , Up: Configuring

5.4.1 The LT_INIT macro

If you are using GNU Autoconf (or Automake), you should add a call to LT_INIT to your configure.ac file. This macro adds many new tests to the configure script so that the generated libtool script will understand the characteristics of the host. It's the most important of a number of macros defined by Libtool:

— Macro: LT_PREREQ (version)

Ensure that a recent enough version of Libtool is being used. If the version of Libtool used for LT_INIT is earlier than version, print an error message to the standard error output and exit with failure (exit status is 63). For example: 

          LT_PREREQ([2.4.2])
— Macro: LT_INIT (options)
— Macro: AC_PROG_LIBTOOL
— Macro: AM_PROG_LIBTOOL

Add support for the --enable-shared, --disable-shared, --enable-static, --disable-static, --with-pic, and --without-pic configure flags.1 AC_PROG_LIBTOOL and AM_PROG_LIBTOOL are deprecated names for older versions of this macro; autoupdate will upgrade your configure.ac files.

By default, this macro turns on shared libraries if they are available, and also enables static libraries if they don't conflict with the shared libraries. You can modify these defaults by passing either disable-shared or disable-static in the option list to LT_INIT, or using AC_DISABLE_SHARED or AC_DISABLE_STATIC. 

          # Turn off shared libraries during beta-testing, since they
          # make the build process take too long.
          LT_INIT([disable-shared])

The user may specify modified forms of the configure flags --enable-shared and --enable-static to choose whether shared or static libraries are built based on the name of the package. For example, to have shared ‘bfd’ and ‘gdb’ libraries built, but not shared ‘libg++’, you can run all three configure scripts as follows: 

          trick$ ./configure --enable-shared=bfd,gdb

In general, specifying --enable-shared=pkgs is the same as configuring with --enable-shared every package named in the comma-separated pkgs list, and every other package with --disable-shared. The --enable-static=pkgs flag behaves similarly, but it uses --enable-static and --disable-static. The same applies to the --enable-fast-install=pkgs flag, which uses --enable-fast-install and --disable-fast-install.

The package name ‘default’ matches any packages that have not set their name in the PACKAGE environment variable.

The --with-pic and --without-pic configure flags can be used to specify whether or not libtool uses PIC objects. By default, libtool uses PIC objects for shared libraries and non-PIC objects for static libraries. The --with-pic option also accepts a comma-separated list of package names. Specifying --with-pic=pkgs is the same as configuring every package in pkgs with --with-pic and every other package with the default configuration. The package name ‘default’ is treated the same as for --enable-shared and --enable-static.

This macro also sets the shell variable LIBTOOL_DEPS, that you can use to automatically update the libtool script if it becomes out-of-date. In order to do that, add to your configure.ac: 

          LT_INIT
          AC_SUBST([LIBTOOL_DEPS])

and, to Makefile.in or Makefile.am: 

          LIBTOOL_DEPS = @LIBTOOL_DEPS@
          libtool: $(LIBTOOL_DEPS)
                  $(SHELL) ./config.status libtool

If you are using GNU Automake, you can omit the assignment, as Automake will take care of it. You'll obviously have to create some dependency on libtool.

Aside from disable-static and disable-shared, there are other options that you can pass to LT_INIT to modify its behaviour. Here is a full list:

‘dlopen’
Enable checking for dlopen support. This option should be used if the package makes use of the -dlopen and -dlpreopen libtool flags, otherwise libtool will assume that the system does not support dlopening.
‘win32-dll’
This option should be used if the package has been ported to build clean dlls on win32 platforms. Usually this means that any library data items are exported with __declspec(dllexport) and imported with __declspec(dllimport). If this macro is not used, libtool will assume that the package libraries are not dll clean and will build only static libraries on win32 hosts.

Provision must be made to pass -no-undefined to libtool in link mode from the package Makefile. Naturally, if you pass -no-undefined, you must ensure that all the library symbols really are defined at link time!

‘disable-fast-install’
Change the default behaviour for LT_INIT to disable optimization for fast installation. The user may still override this default, depending on platform support, by specifying --enable-fast-install to configure.
‘shared’
Change the default behaviour for LT_INIT to enable shared libraries. This is the default on all systems where Libtool knows how to create shared libraries. The user may still override this default by specifying --disable-shared to configure.
‘disable-shared’
Change the default behaviour for LT_INIT to disable shared libraries. The user may still override this default by specifying --enable-shared to configure.
‘static’
Change the default behaviour for LT_INIT to enable static libraries. This is the default on all systems where shared libraries have been disabled for some reason, and on most systems where shared libraries have been enabled. If shared libraries are enabled, the user may still override this default by specifying --disable-static to configure.
‘disable-static’
Change the default behaviour for LT_INIT to disable static libraries. The user may still override this default by specifying --enable-static to configure.
‘pic-only’
Change the default behaviour for libtool to try to use only PIC objects. The user may still override this default by specifying --without-pic to configure.
‘no-pic’
Change the default behaviour of libtool to try to use only non-PIC objects. The user may still override this default by specifying --with-pic to configure.
— Macro: LT_LANG (language)

Enable libtool support for the language given if it has not yet already been enabled. Languages accepted are “C++”, “Fortran 77”, “Java”, “Go”, and “Windows Resource”.

If Autoconf language support macros such as AC_PROG_CXX are used in your configure.ac, Libtool language support will automatically be enabled.

Conversely using LT_LANG to enable language support for Libtool will automatically enable Autoconf language support as well.

Both of the following examples are therefore valid ways of adding C++ language support to Libtool. 

          LT_INIT
          LT_LANG([C++])

          LT_INIT
          AC_PROG_CXX
— Macro: AC_LIBTOOL_DLOPEN

This macro is deprecated, the ‘dlopen’ option to LT_INIT should be used instead.

— Macro: AC_LIBTOOL_WIN32_DLL

This macro is deprecated, the ‘win32-dll’ option to LT_INIT should be used instead.

— Macro: AC_DISABLE_FAST_INSTALL

This macro is deprecated, the ‘disable-fast-install’ option to LT_INIT should be used instead.

— Macro: AC_DISABLE_SHARED
— Macro: AM_DISABLE_SHARED

Change the default behaviour for LT_INIT to disable shared libraries. The user may still override this default by specifying ‘--enable-shared’. The option ‘disable-shared’ to LT_INIT is a shorthand for this. AM_DISABLE_SHARED is a deprecated alias for AC_DISABLE_SHARED.

— Macro: AC_ENABLE_SHARED
— Macro: AM_ENABLE_SHARED

Change the default behaviour for LT_INIT to enable shared libraries. This is the default on all systems where Libtool knows how to create shared libraries. The user may still override this default by specifying ‘--disable-shared’. The option ‘shared’ to LT_INIT is a shorthand for this. AM_ENABLE_SHARED is a deprecated alias for AC_ENABLE_SHARED.

— Macro: AC_DISABLE_STATIC
— Macro: AM_DISABLE_STATIC

Change the default behaviour for LT_INIT to disable static libraries. The user may still override this default by specifying ‘--enable-static’. The option ‘disable-static’ to LT_INIT is a shorthand for this. AM_DISABLE_STATIC is a deprecated alias for AC_DISABLE_STATIC.

— Macro: AC_ENABLE_STATIC
— Macro: AM_ENABLE_STATIC

Change the default behaviour for LT_INIT to enable static libraries. This is the default on all systems where shared libraries have been disabled for some reason, and on most systems where shared libraries have been enabled. If shared libraries are enabled, the user may still override this default by specifying ‘--disable-static’. The option ‘static’ to LT_INIT is a shorthand for this. AM_ENABLE_STATIC is a deprecated alias for AC_ENABLE_STATIC.

The tests in LT_INIT also recognize the following environment variables:

— Variable: CC

The C compiler that will be used by the generated libtool. If this is not set, LT_INIT will look for gcc or cc.

— Variable: CFLAGS

Compiler flags used to generate standard object files. If this is not set, LT_INIT will not use any such flags. It affects only the way LT_INIT runs tests, not the produced libtool.

— Variable: CPPFLAGS

C preprocessor flags. If this is not set, LT_INIT will not use any such flags. It affects only the way LT_INIT runs tests, not the produced libtool.

— Variable: LD

The system linker to use (if the generated libtool requires one). If this is not set, LT_INIT will try to find out what is the linker used by CC.

— Variable: LDFLAGS

The flags to be used by libtool when it links a program. If this is not set, LT_INIT will not use any such flags. It affects only the way LT_INIT runs tests, not the produced libtool.

— Variable: LIBS

The libraries to be used by LT_INIT when it links a program. If this is not set, LT_INIT will not use any such flags. It affects only the way LT_INIT runs tests, not the produced libtool.

— Variable: NM

Program to use rather than checking for nm.

— Variable: RANLIB

Program to use rather than checking for ranlib.

— Variable: LN_S

A command that creates a link of a program, a soft-link if possible, a hard-link otherwise. LT_INIT will check for a suitable program if this variable is not set.

— Variable: DLLTOOL

Program to use rather than checking for dlltool. Only meaningful for Cygwin/MS-Windows.

— Variable: OBJDUMP

Program to use rather than checking for objdump. Only meaningful for Cygwin/MS-Windows.

— Variable: AS

Program to use rather than checking for as. Only used on Cygwin/MS-Windows at the moment.

— Variable: MANIFEST_TOOL

Program to use rather than checking for mt, the Manifest Tool. Only used on Cygwin/MS-Windows at the moment.

With 1.3 era libtool, if you wanted to know any details of what libtool had discovered about your architecture and environment, you had to run the script with --config and grep through the results. This idiom was supported up to and including 1.5.x era libtool, where it was possible to call the generated libtool script from configure.ac as soon as LT_INIT had completed. However, one of the features of libtool 1.4 was that the libtool configuration was migrated out of a separate ltconfig file, and added to the LT_INIT macro (nee AC_PROG_LIBTOOL), so the results of the configuration tests were available directly to code in configure.ac, rendering the call out to the generated libtool script obsolete.

Starting with libtool 2.0, the multipass generation of the libtool script has been consolidated into a single config.status pass, which happens after all the code in configure.ac has completed. The implication of this is that the libtool script does not exist during execution of code from configure.ac, and so obviously it cannot be called for --config details anymore. If you are upgrading projects that used this idiom to libtool 2.0 or newer, you should replace those calls with direct references to the equivalent Autoconf shell variables that are set by the configure time tests before being passed to config.status for inclusion in the generated libtool script.

— Macro: LT_OUTPUT

By default, the configured libtool script is generated by the call to AC_OUTPUT command, and there is rarely any need to use libtool from configure. However, sometimes it is necessary to run configure time compile and link tests using libtool. You can add LT_OUTPUT to your configure.ac any time after LT_INIT and any LT_LANG calls; that done, libtool will be created by a specially generated config.lt file, and available for use in later tests.

Also, when LT_OUTPUT is used, for backwards compatibility with Automake regeneration rules, config.status will call config.lt to regenerate libtool, rather than generating the file itself.

When you invoke the libtoolize program (see Invoking libtoolize), it will tell you where to find a definition of LT_INIT. If you use Automake, the aclocal program will automatically add LT_INIT support to your configure script when it sees the invocation of LT_INIT in configure.ac.

Because of these changes, and the runtime version compatibility checks Libtool now executes, we now advise against including a copy of libtool.m4 (and brethren) in acinclude.m4. Instead, you should set your project macro directory with AC_CONFIG_MACRO_DIR. When you libtoolize your project, a copy of the relevant macro definitions will be placed in your AC_CONFIG_MACRO_DIR, where aclocal can reference them directly from aclocal.m4.

Footnotes

[1] LT_INIT requires that you define the Makefile variable top_builddir in your Makefile.in. Automake does this automatically, but Autoconf users should set it to the relative path to the top of your build directory (../.., for example).