libtool: Distributing libltdl
1
1 11.6 How to distribute libltdl with your package
1 ================================================
1
1 Even though libltdl is installed together with libtool, you may wish to
1 include libltdl in the distribution of your package, for the convenience
1 of users of your package that don't have libtool or libltdl installed,
1 or if you are using features of a very new version of libltdl that you
1 don't expect your users to have yet. In such cases, you must decide
1 what flavor of libltdl you want to use: a convenience library or an
1 installable libtool library.
1
1 The most simplistic way to add 'libltdl' to your package is to copy
1 all the 'libltdl' source files to a subdirectory within your package and
1 to build and link them along with the rest of your sources. To help you
1 do this, the m4 macros for Autoconf are available in 'ltdl.m4'. You
1 must ensure that they are available in 'aclocal.m4' before you run
1 Autoconf(1). Having made the macros available, you must add a call to
1 the 'LTDL_INIT' macro (after the call to 'LT_INIT') to your package's
1 'configure.ac' to perform the configure time checks required to build
1 the library correctly. Unfortunately, this method has problems if you
1 then try to link the package binaries with an installed libltdl, or a
1 library that depends on libltdl, because of the duplicate symbol
1 definitions. For example, ultimately linking against two different
1 versions of libltdl, or against both a local convenience library and an
1 installed libltdl is bad. Ensuring that only one copy of the libltdl
1 sources are linked into any program is left as an exercise for the
1 reader.
1
1 -- Macro: LT_CONFIG_LTDL_DIR (DIRECTORY)
1 Declare DIRECTORY to be the location of the 'libltdl' source files,
11 for 'libtoolize --ltdl' to place them. ⇒Invoking
libtoolize, for more details. Provided that you add an
1 appropriate 'LT_CONFIG_LTDL_DIR' call in your 'configure.ac' before
1 calling 'libtoolize', the appropriate 'libltdl' files will be
1 installed automatically.
1
1 -- Macro: LTDL_INIT (OPTIONS)
1 -- Macro: LT_WITH_LTDL
1 -- Macro: AC_WITH_LTDL
1 'AC_WITH_LTDL' and 'LT_WITH_LTDL' are deprecated names for older
1 versions of this macro; 'autoupdate' will update your
1 'configure.ac' file.
1
1 This macro adds the following options to the 'configure' script:
1
1 '--with-ltdl-include INSTALLED-LTDL-HEADER-DIR'
1 The 'LTDL_INIT' macro will look in the standard header file
1 locations to find the installed 'libltdl' headers. If
1 'LTDL_INIT' can't find them by itself, the person who builds
1 your package can use this option to tell 'configure' where the
1 installed 'libltdl' headers are.
1
1 '--with-ltdl-lib INSTALLED-LTDL-LIBRARY-DIR'
1 Similarly, the person building your package can use this
1 option to help 'configure' find the installed 'libltdl.la'.
1
1 '--with-included-ltdl'
1 If there is no installed 'libltdl', or in any case if the
1 person building your package would rather use the 'libltdl'
1 sources shipped with the package in the subdirectory named by
1 'LT_CONFIG_LTDL_DIR', they should pass this option to
1 'configure'.
1
1 If the '--with-included-ltdl' is not passed at configure time, and
1 an installed 'libltdl' is not found(2), then 'configure' will exit
1 immediately with an error that asks the user to either specify the
1 location of an installed 'libltdl' using the '--with-ltdl-include'
1 and '--with-ltdl-lib' options, or to build with the 'libltdl'
1 sources shipped with the package by passing '--with-included-ltdl'.
1
1 If an installed 'libltdl' is found, then 'LIBLTDL' is set to the
1 link flags needed to use it, and 'LTDLINCL' to the preprocessor
1 flags needed to find the installed headers, and 'LTDLDEPS' will be
1 empty. Note, however, that no version checking is performed. You
1 should manually check for the 'libltdl' features you need in
1 'configure.ac':
1
1 LT_INIT([dlopen])
1 LTDL_INIT
1
1 # The lt_dladvise_init symbol was added with libtool-2.2
1 if test yes != "$with_included_ltdl"; then
1 save_CFLAGS=$CFLAGS
1 save_LDFLAGS=$LDFLAGS
1 CFLAGS="$CFLAGS $LTDLINCL"
1 LDFLAGS="$LDFLAGS $LIBLTDL"
1 AC_CHECK_LIB([ltdl], [lt_dladvise_init],
1 [],
1 [AC_MSG_ERROR([installed libltdl is too old])])
1 LDFLAGS=$save_LDFLAGS
1 CFLAGS=$save_CFLAGS
1 fi
1
1 OPTIONS may include no more than one of the following build modes
1 depending on how you want your project to build 'libltdl':
1 'nonrecursive', 'recursive', or 'subproject'. In order for
1 'libtoolize' to detect this option correctly, if you supply one of
1 these arguments, they must be given literally (i.e., macros or
1 shell variables that expand to the correct ltdl mode will not
1 work).
1
1 'nonrecursive'
1 This is how the Libtool project distribution builds the
1 'libltdl' we ship and install. If you wish to use Automake to
1 build 'libltdl' without invoking a recursive make to descend
1 into the 'libltdl' subdirectory, then use this option. You
1 will need to set your configuration up carefully to make this
1 work properly, and you will need releases of Autoconf and
1 Automake that support 'subdir-objects' and 'LIBOBJDIR'
1 properly. In your 'configure.ac', add:
1
1 AM_INIT_AUTOMAKE([subdir-objects])
1 AC_CONFIG_HEADERS([config.h])
1 LT_CONFIG_LTDL_DIR([libltdl])
1 LT_INIT([dlopen])
1 LTDL_INIT([nonrecursive])
1
1 You _have to_ use a config header, but it may have a name
1 different than 'config.h'.
1
1 Also, add the following near the top of your 'Makefile.am':
1
1 AM_CPPFLAGS =
1 AM_LDFLAGS =
1
1 BUILT_SOURCES =
1 EXTRA_DIST =
1 CLEANFILES =
1 MOSTLYCLEANFILES =
1
1 include_HEADERS =
1 noinst_LTLIBRARIES =
1 lib_LTLIBRARIES =
1 EXTRA_LTLIBRARIES =
1
1 include libltdl/ltdl.mk
1
1 Unless you build no other libraries from this 'Makefile.am',
1 you will also need to change 'lib_LTLIBRARIES' to assign with
1 '+=' so that the 'libltdl' targets declared in 'ltdl.mk' are
1 not overwritten.
1
1 'recursive'
1 This build mode still requires that you use Automake, but (in
1 contrast with 'nonrecursive') uses the more usual device of
1 starting another 'make' process in the 'libltdl' subdirectory.
1 To use this mode, you should add to your 'configure.ac':
1
1 AM_INIT_AUTOMAKE
1 AC_CONFIG_HEADERS([config.h])
1 LT_CONFIG_LTDL_DIR([libltdl])
1 LT_INIT([dlopen])
1 LTDL_INIT([recursive])
1 AC_CONFIG_FILES([libltdl/Makefile])
1
1 Again, you _have to_ use a config header, but it may have a
1 name different than 'config.h' if you like.
1
1 Also, add this to your 'Makefile.am':
1
1 SUBDIRS = libltdl
1
1 'subproject'
1 This mode is the default unless you explicitly add 'recursive'
1 or 'nonrecursive' to your 'LTDL_INIT' options; 'subproject' is
1 the only mode supported by previous releases of libltdl. Even
1 if you do not use Autoconf in the parent project, then, in
1 'subproject' mode, still 'libltdl' contains all the necessary
1 files to configure and build itself - you just need to arrange
1 for your build system to call 'libltdl/configure' with
1 appropriate options, and then run 'make' in the 'libltdl'
1 subdirectory.
1
1 If you _are_ using Autoconf and Automake, then you will need
1 to add the following to your 'configure.ac':
1
1 LT_CONFIG_LTDL_DIR([libltdl])
1 LTDL_INIT
1
1 and to 'Makefile.am':
1
1 SUBDIRS = libltdl
1
1 Aside from setting the libltdl build mode, there are other keywords
1 that you can pass to 'LTDL_INIT' to modify its behavior when
1 '--with-included-ltdl' has been given:
1
1 'convenience'
1 This is the default unless you explicitly add 'installable' to
1 your 'LTDL_INIT' options.
1
1 This keyword will cause options to be passed to the
1 'configure' script in the subdirectory named by
1 'LT_CONFIG_LTDL_DIR' to cause it to be built as a convenience
1 library. If you're not using automake, you will need to
1 define 'top_build_prefix', 'top_builddir', and 'top_srcdir' in
1 your makefile so that 'LIBLTDL', 'LTDLDEPS', and 'LTDLINCL'
1 expand correctly.
1
1 One advantage of the convenience library is that it is not
1 installed, so the fact that you use 'libltdl' will not be
1 apparent to the user, and it won't overwrite a pre-installed
1 version of 'libltdl' the system might already have in the
1 installation directory. On the other hand, if you want to
1 upgrade 'libltdl' for any reason (e.g. a bugfix) you'll have
1 to recompile your package instead of just replacing the shared
1 installed version of 'libltdl'. However, if your programs or
1 libraries are linked with other libraries that use such a
1 pre-installed version of 'libltdl', you may get linker errors
1 or run-time crashes. Another problem is that you cannot link
1 the convenience library into more than one libtool library,
1 then link a single program with those libraries, because you
1 may get duplicate symbols. In general you can safely use the
1 convenience library in programs that don't depend on other
1 libraries that might use 'libltdl' too.
1
1 'installable'
1 This keyword will pass options to the 'configure' script in
1 the subdirectory named by 'LT_CONFIG_LTDL_DIR' to cause it to
1 be built as an installable library. If you're not using
1 automake, you will need to define 'top_build_prefix',
1 'top_builddir' and 'top_srcdir' in your makefile so that
1 'LIBLTDL', 'LTDLDEPS', and 'LTDLINCL' are expanded properly.
1
1 Be aware that you could overwrite another 'libltdl' already
1 installed to the same directory if you use this option.
1
1 Whatever method you use, 'LTDL_INIT' will define the shell variable
1 'LIBLTDL' to the link flag that you should use to link with 'libltdl',
1 the shell variable 'LTDLDEPS' to the files that can be used as a
1 dependency in 'Makefile' rules, and the shell variable 'LTDLINCL' to the
1 preprocessor flag that you should use to compile programs that include
1 'ltdl.h'. So, when you want to link a program with libltdl, be it a
1 convenience, installed or installable library, just use '$(LTDLINCL)'
1 for preprocessing and compilation, and '$(LIBLTDL)' for linking.
1
1 * If your package is built using an installed version of 'libltdl',
1 'LIBLTDL' will be set to the compiler flags needed to link against
1 the installed library, 'LTDLDEPS' will be empty, and 'LTDLINCL'
1 will be set to the compiler flags needed to find the 'libltdl'
1 header files.
1
1 * If your package is built using the convenience libltdl, 'LIBLTDL'
1 and 'LTDLDEPS' will be the pathname for the convenience version of
1 libltdl (starting with '${top_builddir}/' or '${top_build_prefix}')
1 and 'LTDLINCL' will be '-I' followed by the directory that contains
1 'ltdl.h' (starting with '${top_srcdir}/').
1
1 * If an installable version of the included 'libltdl' is being built,
1 its pathname starting with '${top_builddir}/' or
1 '${top_build_prefix}', will be stored in 'LIBLTDL' and 'LTDLDEPS',
1 and 'LTDLINCL' will be set just like in the case of convenience
1 library.
1
1 You should probably also use the 'dlopen' option to 'LT_INIT' in your
1 'configure.ac', otherwise libtool will assume no dlopening mechanism is
1 supported, and revert to dlpreopening, which is probably not what you
1 want. Avoid using the '-static', '-static-libtool-libs', or
1 '-all-static' switches when linking programs with libltdl. This will
1 not work on all platforms, because the dlopening functions may not be
1 available for static linking.
1
1 The following example shows you how to embed an installable libltdl
1 in your package. In order to use the convenience variant, just replace
1 the 'LTDL_INIT' option 'installable' with 'convenience'. We assume that
1 libltdl was embedded using 'libtoolize --ltdl'.
1
1 configure.ac:
1 ...
1 # Name the subdirectory that contains libltdl sources
1 LT_CONFIG_LTDL_DIR([libltdl])
1
1 # Configure libtool with dlopen support if possible
1 LT_INIT([dlopen])
1
1 # Enable building of the installable libltdl library
1 LTDL_INIT([installable])
1 ...
1
1 Makefile.am:
1 ...
1 SUBDIRS = libltdl
1
1 AM_CPPFLAGS = $(LTDLINCL)
1
1 myprog_LDFLAGS = -export-dynamic
1 myprog_LDADD = $(LIBLTDL) -dlopen self -dlopen foo1.la
1 myprog_DEPENDENCIES = $(LTDLDEPS) foo1.la
1 ...
1
1 -- Macro: LTDL_INSTALLABLE
1 -- Macro: AC_LIBLTDL_INSTALLABLE
1 These macros are deprecated, the 'installable' option to
1 'LTDL_INIT' should be used instead.
1
1 -- Macro: LTDL_CONVENIENCE
1 -- Macro: AC_LIBLTDL_CONVENIENCE
1 These macros are deprecated, the 'convenience' option to
1 'LTDL_INIT' should be used instead.
1
1 ---------- Footnotes ----------
1
1 (1) We used to recommend adding the contents of 'ltdl.m4' to
1 'acinclude.m4', but with 'aclocal' from a modern Automake (1.8 or newer)
1 and this release of libltdl that is not only unnecessary but makes it
1 easy to forget to upgrade 'acinclude.m4' if you move to a different
1 release of libltdl.
1
1 (2) Even if libltdl is installed, 'LTDL_INIT' may fail to detect it
1 if libltdl depends on symbols provided by libraries other than the C
1 library.
1