libtool: LT_INIT
1
1 5.4.1 The 'LT_INIT' macro
1 -------------------------
1
1 If you are using GNU Autoconf (or Automake), you should add a call to
1 'LT_INIT' to your 'configure.ac' file. This macro adds many new tests
1 to the 'configure' script so that the generated libtool script will
1 understand the characteristics of the host. It's the most important of
1 a number of macros defined by Libtool:
1
1 -- Macro: LT_PREREQ (VERSION)
1 Ensure that a recent enough version of Libtool is being used. If
1 the version of Libtool used for 'LT_INIT' is earlier than VERSION,
1 print an error message to the standard error output and exit with
1 failure (exit status is 63). For example:
1
1 LT_PREREQ([2.4.6])
1
1 -- Macro: LT_INIT (OPTIONS)
1 -- Macro: AC_PROG_LIBTOOL
1 -- Macro: AM_PROG_LIBTOOL
1 Add support for the '--enable-shared', '--disable-shared',
1 '--enable-static', '--disable-static', '--with-pic', and
1 '--without-pic' 'configure' flags.(1) 'AC_PROG_LIBTOOL' and
1 'AM_PROG_LIBTOOL' are deprecated names for older versions of this
1 macro; 'autoupdate' will upgrade your 'configure.ac' files.
1
1 By default, this macro turns on shared libraries if they are
1 available, and also enables static libraries if they don't conflict
1 with the shared libraries. You can modify these defaults by
1 passing either 'disable-shared' or 'disable-static' in the option
1 list to 'LT_INIT', or using 'AC_DISABLE_SHARED' or
1 'AC_DISABLE_STATIC'.
1
1 # Turn off shared libraries during beta-testing, since they
1 # make the build process take too long.
1 LT_INIT([disable-shared])
1
1 The user may specify modified forms of the configure flags
1 '--enable-shared' and '--enable-static' to choose whether shared or
1 static libraries are built based on the name of the package. For
1 example, to have shared 'bfd' and 'gdb' libraries built, but not
1 shared 'libg++', you can run all three 'configure' scripts as
1 follows:
1
1 trick$ ./configure --enable-shared=bfd,gdb
1
1 In general, specifying '--enable-shared=PKGS' is the same as
1 configuring with '--enable-shared' every package named in the
1 comma-separated PKGS list, and every other package with
1 '--disable-shared'. The '--enable-static=PKGS' flag behaves
1 similarly, but it uses '--enable-static' and '--disable-static'.
1 The same applies to the '--enable-fast-install=PKGS' flag, which
1 uses '--enable-fast-install' and '--disable-fast-install'.
1
1 The package name 'default' matches any packages that have not set
1 their name in the 'PACKAGE' environment variable.
1
1 The '--with-pic' and '--without-pic' configure flags can be used to
1 specify whether or not 'libtool' uses PIC objects. By default,
1 'libtool' uses PIC objects for shared libraries and non-PIC objects
1 for static libraries. The '--with-pic' option also accepts a
1 comma-separated list of package names. Specifying
1 '--with-pic=PKGS' is the same as configuring every package in PKGS
1 with '--with-pic' and every other package with the default
1 configuration. The package name 'default' is treated the same as
1 for '--enable-shared' and '--enable-static'.
1
1 This macro also sets the shell variable 'LIBTOOL_DEPS', that you
1 can use to automatically update the libtool script if it becomes
1 out-of-date. In order to do that, add to your 'configure.ac':
1
1 LT_INIT
1 AC_SUBST([LIBTOOL_DEPS])
1
1 and, to 'Makefile.in' or 'Makefile.am':
1
1 LIBTOOL_DEPS = @LIBTOOL_DEPS@
1 libtool: $(LIBTOOL_DEPS)
1 $(SHELL) ./config.status libtool
1
1 If you are using GNU Automake, you can omit the assignment, as
1 Automake will take care of it. You'll obviously have to create
1 some dependency on 'libtool'.
1
1 Aside from 'disable-static' and 'disable-shared', there are other
1 options that you can pass to 'LT_INIT' to modify its behaviour.
1 Here is a full list:
1
1 'dlopen'
1 Enable checking for dlopen support. This option should be
1 used if the package makes use of the '-dlopen' and
1 '-dlpreopen' libtool flags, otherwise libtool will assume that
1 the system does not support dlopening.
1
1 'win32-dll'
1 This option should be used if the package has been ported to
1 build clean dlls on win32 platforms. Usually this means that
1 any library data items are exported with
1 '__declspec(dllexport)' and imported with
1 '__declspec(dllimport)'. If this macro is not used, libtool
1 will assume that the package libraries are not dll clean and
1 will build only static libraries on win32 hosts.
1
1 Provision must be made to pass '-no-undefined' to 'libtool' in
1 link mode from the package 'Makefile'. Naturally, if you pass
1 '-no-undefined', you must ensure that all the library symbols
1 *really are* defined at link time!
1
1 'aix-soname=aix'
1 'aix-soname=svr4'
1 'aix-soname=both'
1 Enable the '--with-aix-soname' to 'configure', which the user
1 can pass to override the given default.
1
1 By default (and *always* in releases prior to 2.4.4), Libtool
1 always behaves as if 'aix-soname=aix' is given, with no
1 'configure' option for the user to override. Specifically,
1 when the '-brtl' linker flag is seen in 'LDFLAGS' at
1 build-time, static archives are built from static objects
1 only, otherwise, traditional AIX shared library archives of
1 shared objects using in-archive versioning are built (with the
1 '.a' file extension!). Similarly, with '-brtl' in 'LDFLAGS',
1 libtool shared archives are built from shared objects, without
1 any filename-based versioning; and without '-brtl' no shared
1 archives are built at all.
1
1 When 'aix-soname=svr4' option is given, or the
1 '--with-aix-soname=svr4' 'configure' option is passed, static
1 archives are always created from static objects, even without
1 '-brtl' in 'LDFLAGS'. Shared archives are made from shared
1 objects, and filename based versioning is enabled.
1
1 When 'aix-soname=both' option is given, or the
1 '--with-aix-soname=svr4' 'configure' option is passed, static
1 archives are built traditionally (as 'aix-soname=aix'), and
1 both kinds of shared archives are built. The '.la'
1 pseudo-archive specifies one or the other depending on whether
1 '-brtl' is specified in 'LDFLAGS' when the library is built.
1
1 'disable-fast-install'
1 Change the default behaviour for 'LT_INIT' to disable
1 optimization for fast installation. The user may still
1 override this default, depending on platform support, by
1 specifying '--enable-fast-install' to 'configure'.
1
1 'shared'
1 Change the default behaviour for 'LT_INIT' to enable shared
1 libraries. This is the default on all systems where Libtool
1 knows how to create shared libraries. The user may still
1 override this default by specifying '--disable-shared' to
1 'configure'.
1
1 'disable-shared'
1 Change the default behaviour for 'LT_INIT' to disable shared
1 libraries. The user may still override this default by
1 specifying '--enable-shared' to 'configure'.
1
1 'static'
1 Change the default behaviour for 'LT_INIT' to enable static
1 libraries. This is the default on all systems where shared
1 libraries have been disabled for some reason, and on most
1 systems where shared libraries have been enabled. If shared
1 libraries are enabled, the user may still override this
1 default by specifying '--disable-static' to 'configure'.
1
1 'disable-static'
1 Change the default behaviour for 'LT_INIT' to disable static
1 libraries. The user may still override this default by
1 specifying '--enable-static' to 'configure'.
1
1 'pic-only'
1 Change the default behaviour for 'libtool' to try to use only
1 PIC objects. The user may still override this default by
1 specifying '--without-pic' to 'configure'.
1
1 'no-pic'
1 Change the default behaviour of 'libtool' to try to use only
1 non-PIC objects. The user may still override this default by
1 specifying '--with-pic' to 'configure'.
1
1 -- Macro: LT_LANG (LANGUAGE)
1 Enable 'libtool' support for the language given if it has not yet
1 already been enabled. Languages accepted are "C++", "Fortran 77",
1 "Java", "Go", and "Windows Resource".
1
1 If Autoconf language support macros such as 'AC_PROG_CXX' are used
1 in your 'configure.ac', Libtool language support will automatically
1 be enabled.
1
1 Conversely using 'LT_LANG' to enable language support for Libtool
1 will automatically enable Autoconf language support as well.
1
1 Both of the following examples are therefore valid ways of adding
1 C++ language support to Libtool.
1
1 LT_INIT
1 LT_LANG([C++])
1
1 LT_INIT
1 AC_PROG_CXX
1
1 -- Macro: AC_LIBTOOL_DLOPEN
1 This macro is deprecated, the 'dlopen' option to 'LT_INIT' should
1 be used instead.
1
1 -- Macro: AC_LIBTOOL_WIN32_DLL
1 This macro is deprecated, the 'win32-dll' option to 'LT_INIT'
1 should be used instead.
1
1 -- Macro: AC_DISABLE_FAST_INSTALL
1 This macro is deprecated, the 'disable-fast-install' option to
1 'LT_INIT' should be used instead.
1
1 -- Macro: AC_DISABLE_SHARED
1 -- Macro: AM_DISABLE_SHARED
1 Change the default behaviour for 'LT_INIT' to disable shared
1 libraries. The user may still override this default by specifying
1 '--enable-shared'. The option 'disable-shared' to 'LT_INIT' is a
1 shorthand for this. 'AM_DISABLE_SHARED' is a deprecated alias for
1 'AC_DISABLE_SHARED'.
1
1 -- Macro: AC_ENABLE_SHARED
1 -- Macro: AM_ENABLE_SHARED
1 Change the default behaviour for 'LT_INIT' to enable shared
1 libraries. This is the default on all systems where Libtool knows
1 how to create shared libraries. The user may still override this
1 default by specifying '--disable-shared'. The option 'shared' to
1 'LT_INIT' is a shorthand for this. 'AM_ENABLE_SHARED' is a
1 deprecated alias for 'AC_ENABLE_SHARED'.
1
1 -- Macro: AC_DISABLE_STATIC
1 -- Macro: AM_DISABLE_STATIC
1 Change the default behaviour for 'LT_INIT' to disable static
1 libraries. The user may still override this default by specifying
1 '--enable-static'. The option 'disable-static' to 'LT_INIT' is a
1 shorthand for this. 'AM_DISABLE_STATIC' is a deprecated alias for
1 'AC_DISABLE_STATIC'.
1
1 -- Macro: AC_ENABLE_STATIC
1 -- Macro: AM_ENABLE_STATIC
1 Change the default behaviour for 'LT_INIT' to enable static
1 libraries. This is the default on all systems where shared
1 libraries have been disabled for some reason, and on most systems
1 where shared libraries have been enabled. If shared libraries are
1 enabled, the user may still override this default by specifying
1 '--disable-static'. The option 'static' to 'LT_INIT' is a
1 shorthand for this. 'AM_ENABLE_STATIC' is a deprecated alias for
1 'AC_ENABLE_STATIC'.
1
1 The tests in 'LT_INIT' also recognize the following environment
1 variables:
1
1 -- Variable: CC
1 The C compiler that will be used by the generated 'libtool'. If
1 this is not set, 'LT_INIT' will look for 'gcc' or 'cc'.
1
1 -- Variable: CFLAGS
1 Compiler flags used to generate standard object files. If this is
1 not set, 'LT_INIT' will not use any such flags. It affects only
1 the way 'LT_INIT' runs tests, not the produced 'libtool'.
1
1 -- Variable: CPPFLAGS
1 C preprocessor flags. If this is not set, 'LT_INIT' will not use
1 any such flags. It affects only the way 'LT_INIT' runs tests, not
1 the produced 'libtool'.
1
1 -- Variable: LD
1 The system linker to use (if the generated 'libtool' requires one).
1 If this is not set, 'LT_INIT' will try to find out what is the
1 linker used by 'CC'.
1
1 -- Variable: LDFLAGS
1 The flags to be used by 'libtool' when it links a program. If this
1 is not set, 'LT_INIT' will not use any such flags. It affects only
1 the way 'LT_INIT' runs tests, not the produced 'libtool'.
1
1 -- Variable: LIBS
1 The libraries to be used by 'LT_INIT' when it links a program. If
1 this is not set, 'LT_INIT' will not use any such flags. It affects
1 only the way 'LT_INIT' runs tests, not the produced 'libtool'.
1
1 -- Variable: NM
1 Program to use rather than checking for 'nm'.
1
1 -- Variable: RANLIB
1 Program to use rather than checking for 'ranlib'.
1
1 -- Variable: LN_S
1 A command that creates a link of a program, a soft-link if
1 possible, a hard-link otherwise. 'LT_INIT' will check for a
1 suitable program if this variable is not set.
1
1 -- Variable: DLLTOOL
1 Program to use rather than checking for 'dlltool'. Only meaningful
1 for Cygwin/MS-Windows.
1
1 -- Variable: OBJDUMP
1 Program to use rather than checking for 'objdump'. Only meaningful
1 for Cygwin/MS-Windows.
1
1 -- Variable: AS
1 Program to use rather than checking for 'as'. Only used on
1 Cygwin/MS-Windows at the moment.
1
1 -- Variable: MANIFEST_TOOL
1 Program to use rather than checking for 'mt', the Manifest Tool.
1 Only used on Cygwin/MS-Windows at the moment.
1
1 -- Variable: LT_SYS_LIBRARY_PATH
1 Libtool has heuristics for the system search path for
1 runtime-loaded libraries. If the guessed default does not match
1 the setup of the host system, this variable can be used to modify
1 that path list, as follows ('LT_SYS_LIBRARY_PATH' is a
1 colon-delimited list like 'PATH'):
1 * 'path:' The heuristically determined paths will be appened
1 after the trailing colon;
1 * ':path' The heuristically determined paths will be prepended
1 before the leading colon;
1 * 'path::path' The heuristically determined paths will be
1 inserted between the double colons;
1 * 'path' With no dangling colons, the heuristically determined
1 paths will be ignored entirely.
1
1 With 1.3 era libtool, if you wanted to know any details of what
1 libtool had discovered about your architecture and environment, you had
1 to run the script with '--config' and grep through the results. This
1 idiom was supported up to and including 1.5.x era libtool, where it was
1 possible to call the generated libtool script from 'configure.ac' as
1 soon as 'LT_INIT' had completed. However, one of the features of
1 libtool 1.4 was that the libtool configuration was migrated out of a
1 separate 'ltconfig' file, and added to the 'LT_INIT' macro (nee
1 'AC_PROG_LIBTOOL'), so the results of the configuration tests were
1 available directly to code in 'configure.ac', rendering the call out to
1 the generated libtool script obsolete.
1
1 Starting with libtool 2.0, the multipass generation of the libtool
1 script has been consolidated into a single 'config.status' pass, which
1 happens after all the code in 'configure.ac' has completed. The
1 implication of this is that the libtool script does not exist during
1 execution of code from 'configure.ac', and so obviously it cannot be
1 called for '--config' details anymore. If you are upgrading projects
1 that used this idiom to libtool 2.0 or newer, you should replace those
1 calls with direct references to the equivalent Autoconf shell variables
1 that are set by the configure time tests before being passed to
1 'config.status' for inclusion in the generated libtool script.
1
1 -- Macro: LT_OUTPUT
1 By default, the configured 'libtool' script is generated by the
1 call to 'AC_OUTPUT' command, and there is rarely any need to use
1 'libtool' from 'configure'. However, sometimes it is necessary to
1 run configure time compile and link tests using 'libtool'. You can
1 add 'LT_OUTPUT' to your 'configure.ac' any time after 'LT_INIT' and
1 any 'LT_LANG' calls; that done, 'libtool' will be created by a
1 specially generated 'config.lt' file, and available for use in
1 later tests.
1
1 Also, when 'LT_OUTPUT' is used, for backwards compatibility with
1 Automake regeneration rules, 'config.status' will call 'config.lt'
1 to regenerate 'libtool', rather than generating the file itself.
1
11 When you invoke the 'libtoolize' program (⇒Invoking
libtoolize), it will tell you where to find a definition of 'LT_INIT'.
1 If you use Automake, the 'aclocal' program will automatically add
1 'LT_INIT' support to your 'configure' script when it sees the invocation
1 of 'LT_INIT' in 'configure.ac'.
1
1 Because of these changes, and the runtime version compatibility
1 checks Libtool now executes, we now advise *against* including a copy of
1 'libtool.m4' (and brethren) in 'acinclude.m4'. Instead, you should set
1 your project macro directory with 'AC_CONFIG_MACRO_DIRS'. When you
1 'libtoolize' your project, a copy of the relevant macro definitions will
1 be placed in your 'AC_CONFIG_MACRO_DIRS', where 'aclocal' can reference
1 them directly from 'aclocal.m4'.
1
1 ---------- Footnotes ----------
1
1 (1) 'LT_INIT' requires that you define the 'Makefile' variable
1 'top_builddir' in your 'Makefile.in'. Automake does this automatically,
1 but Autoconf users should set it to the relative path to the top of your
1 build directory ('../..', for example).
1